phase-memory/docs/local-persistence.md

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

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:

{
  "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:

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:

PYTHONPATH=src python3 -m phase_memory.cli store export \
  --store .phase-memory-local \
  --graph-id local-dev

Inspect repair diagnostics:

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.