---
id: PMEM-WP-0003
type: workplan
title: "File-Backed Stores And Event Path Runtime"
domain: markitect
repo: phase-memory
status: finished
owner: phase-memory
topic_slug: local-persistence
planning_priority: P1
planning_order: 30
related_workplans:
  - PMEM-WP-0002
created: "2026-05-18"
updated: "2026-05-18"
state_hub_workstream_id: "c15d2f61-449b-48fa-9e4d-ea22a9b419b2"
---

# PMEM-WP-0003: File-Backed Stores And Event Path Runtime

## Goal

Add a local-first durable adapter layer that can persist profiles, graph
records, and append-only memory events without requiring external
infrastructure.

This should move the project from deterministic in-memory tests to a useful
developer runtime while preserving the INTENT.md principle that durable writes
are explicit, inspectable, and policy-aware.

## Current Evidence

The repository has port protocols and in-memory adapters, but no file-backed
store, event replay, export, import, or durable local graph snapshot format.
The memory event model also exists, but conversational paths are not yet
first-class runtime objects.

## Non-Goals

- Do not choose a production graph database.
- Do not implement a generic vector database.
- Do not add hidden background compaction or deletion.
- Do not make file-backed storage the only adapter option.

## Implementation Update - 2026-05-18

The local persistence and event-path runtime slice is complete.

Implemented outputs:

- `FileBackedMemoryGraphStore` stores profiles, nodes, edges, and path records
  as deterministic JSON under a versioned local workspace layout.
- `JsonlMemoryEventLog` provides append-only event logging, duplicate event id
  detection, kind filtering, graph replay, and corruption/schema diagnostics.
- `JsonlAuditSink` records local runtime audit events into `audit.jsonl`.
- `MemoryPath` and `phase_memory.paths` model branch, merge, abandon, compact,
  and structured path-event behavior without transcript storage.
- `PhaseMemoryRuntime` can export local graph state, report repair diagnostics,
  and apply lifecycle actions only when review-required actions include an
  explicit approval marker.
- CLI store commands can import fixtures, export local graph envelopes, and
  report repair diagnostics.
- `docs/local-persistence.md` documents the storage layout, CLI flow, path
  model, and review-gated apply rule.

Validation:

- `python3 -m pytest` -> 31 passed.

## T01 - Define local storage layout

```task
id: PMEM-WP-0003-T01
status: done
priority: high
state_hub_task_id: "37d082c7-c019-4ecd-8655-94f8f27807ff"
```

Define a simple versioned local storage layout for:

- profiles
- nodes
- edges
- events
- activation plans
- audit records
- runtime metadata

Prefer JSON and JSONL formats for this slice unless a concrete requirement
forces SQLite.

Output: documented storage layout, schema version fields, and fixture examples.

## T02 - Implement a file-backed graph store

```task
id: PMEM-WP-0003-T02
status: done
priority: high
state_hub_task_id: "c417f7ec-0423-4723-91c3-3b4681e30ec3"
```

Implement a deterministic adapter for the `MemoryGraphStore` protocol that can:

- save and load profiles
- save and load nodes
- save and load edges
- list nodes by kind
- list edges by source or target
- export a Markitect-compatible graph envelope

Output: adapter implementation and tests for round-trip behavior.

## T03 - Implement a JSONL event log

```task
id: PMEM-WP-0003-T03
status: done
priority: high
state_hub_task_id: "1d3b3ffb-fc9b-401f-a77f-cfad4a4f6b72"
```

Implement an append-only `MemoryEventLog` adapter with:

- duplicate event id detection
- deterministic ordering
- kind filtering
- replay into graph snapshots where possible
- corruption diagnostics for malformed lines

Output: event log adapter and tests for append, list, replay, and diagnostics.

## T04 - Model conversational paths explicitly

```task
id: PMEM-WP-0003-T04
status: done
priority: high
state_hub_task_id: "43d5863c-f2db-441e-8f3e-7e1843b6bc33"
```

Add first-slice path records for fluid memory:

- path id
- parent path id
- event ids
- active branch marker
- merge marker
- abandoned branch reason
- compaction status

Output: path model, path event helpers, and tests that show branch, merge, and
abandon flows without requiring transcript storage.

## T05 - Add safe apply behavior behind review gates

```task
id: PMEM-WP-0003-T05
status: done
priority: medium
state_hub_task_id: "e9079c0c-5834-47b2-b1dc-1d97604c96f8"
```

Add an optional runtime operation that applies approved lifecycle actions to a
file-backed store. The operation must reject actions that require review unless
the caller provides an explicit approval marker.

Output: apply operation, approval checks, audit records, and tests that prove
unapproved durable actions are denied.

## T06 - Add import, export, and repair diagnostics

```task
id: PMEM-WP-0003-T06
status: done
priority: medium
state_hub_task_id: "a0597e3e-2f2d-4abf-8fc2-37c914e0ce34"
```

Add local tooling to:

- import Markitect-compatible graph and profile fixtures
- export local state to a graph envelope
- report missing edge endpoints
- report orphaned events
- report unknown schema versions

Output: CLI/runtime helpers and tests for useful diagnostics.

## T07 - Update docs with local persistence examples

```task
id: PMEM-WP-0003-T07
status: done
priority: medium
state_hub_task_id: "60b3bce7-3e73-427b-95d7-d68283503a3c"
```

Document how to create a local memory workspace, import a profile and graph,
append events, inspect paths, and export a graph.

Output: local persistence guide and README pointers.

## Acceptance Criteria

- `python3 -m pytest` passes.
- File-backed adapters satisfy the same public protocols as in-memory adapters.
- A local workspace can be created, inspected, exported, and replayed
  deterministically.
- Review-required actions cannot be applied without an explicit approval
  marker.
- Conversational path branches and merges are represented as structured memory
  events, not only as transcript text.

## Closure Review - 2026-05-18

**Outcome:** All tasks completed.

### Completed

- PMEM-WP-0003-T01 - Define local storage layout
- PMEM-WP-0003-T02 - Implement a file-backed graph store
- PMEM-WP-0003-T03 - Implement a JSONL event log
- PMEM-WP-0003-T04 - Model conversational paths explicitly
- PMEM-WP-0003-T05 - Add safe apply behavior behind review gates
- PMEM-WP-0003-T06 - Add import, export, and repair diagnostics
- PMEM-WP-0003-T07 - Update docs with local persistence examples

### Cancelled

None.

### Carried Forward

Policy enforcement, review record modeling, activation redaction, and richer
audit schema remain in PMEM-WP-0004.