generated from coulomb/repo-seed
92 lines
2.2 KiB
Markdown
92 lines
2.2 KiB
Markdown
# Local Persistence
|
|
|
|
`phase-memory` can run against a versioned local file workspace. This is a
|
|
developer and integration adapter, not a production graph database.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
memory-store/
|
|
phase-memory.json
|
|
profiles/
|
|
<profile-id>.json
|
|
nodes/
|
|
<node-id>.json
|
|
edges/
|
|
<edge-id>.json
|
|
paths/
|
|
<path-id>.json
|
|
activations/
|
|
events.jsonl
|
|
audit.jsonl
|
|
```
|
|
|
|
The root `phase-memory.json` declares:
|
|
|
|
```json
|
|
{
|
|
"schema_version": "phase_memory.local_store.v1"
|
|
}
|
|
```
|
|
|
|
Profiles, nodes, edges, and paths are stored as deterministic JSON files.
|
|
Events and audit records are append-only JSONL files. The current local runtime
|
|
does not compact, delete, or rewrite append-only logs.
|
|
|
|
## CLI
|
|
|
|
Import local fixtures:
|
|
|
|
```bash
|
|
PYTHONPATH=src python3 -m phase_memory.cli store import \
|
|
--store .phase-memory-local \
|
|
--profile tests/fixtures/memory-profile.json \
|
|
--graph tests/fixtures/memory-graph.json
|
|
```
|
|
|
|
Export a Markitect-compatible graph envelope:
|
|
|
|
```bash
|
|
PYTHONPATH=src python3 -m phase_memory.cli store export \
|
|
--store .phase-memory-local \
|
|
--graph-id local-dev
|
|
```
|
|
|
|
Inspect repair diagnostics:
|
|
|
|
```bash
|
|
PYTHONPATH=src python3 -m phase_memory.cli store repair \
|
|
--store .phase-memory-local
|
|
```
|
|
|
|
Repair diagnostics report malformed JSONL event lines, unknown event schema
|
|
versions, missing edge endpoints, and path records that reference events not
|
|
present in the event log.
|
|
|
|
## Paths
|
|
|
|
Conversational paths are structured records, not transcript blobs. A path can
|
|
record:
|
|
|
|
- `path_id`
|
|
- `parent_path_id`
|
|
- ordered `event_ids`
|
|
- active, merged, abandoned, or compacted state
|
|
- merge target
|
|
- abandoned reason
|
|
- compacted summary id
|
|
|
|
Helper functions in `phase_memory.paths` create, branch, merge, abandon, and
|
|
compact paths while also producing structured path events for the fluid memory
|
|
event log.
|
|
|
|
## Review-Gated Apply
|
|
|
|
Lifecycle planning remains dry-run by default. The runtime exposes an optional
|
|
`apply_lifecycle_actions` operation for local stores. Actions marked
|
|
`requires_review` are denied unless the caller provides an explicit
|
|
`approval_marker`.
|
|
|
|
This keeps the local adapter useful for development while preserving the
|
|
project rule that durable memory changes must be inspectable and deliberate.
|