# 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.