docs: README + plan/ADR for slice 5 (Neo4j GraphBackend)

Updates the POC README with a 'Storage backends' section
documenting the GraphBackend Protocol, the two implementations
(InMemoryGraph and Neo4jGraph), and the LORE_GRAPH_BACKEND
env-var selection in the MCP entry scripts. Adds the slice 5
plan doc (docs/plan/05-slice-neo4j-backend.md in the design
repo) and ADR 0011 capturing the Protocol + dual-write
model decisions.
This commit is contained in:
Lore Engine Dev
2026-06-18 23:45:59 -04:00
parent 4176b95f21
commit 012e111a72
2 changed files with 55 additions and 0 deletions

View File

@@ -35,6 +35,61 @@ The 44 other MCP tools, the consistency engine, the TypeTemplate
polymorphic extension, the plane model, the MCP server wiring. All
deferred to follow-up slices per the design.
## Storage backends (slice 5)
The 36 MCP tools and the consistency engine read from a
`GraphBackend` Protocol (`lore_engine_poc/graph_backend.py`)
with two implementations:
* **InMemoryGraph** (default, pickle-backed). The in-memory
dict-of-dicts from slices 1-11. Used for fast tests, the
CI test suite, and the Docker image's baked-in
`.graph.pkl` (slice 11).
* **Neo4jGraph** (slice 5.3+). A `neo4j:5` container with
the reified `:Relation` shape (ADR 0009). The production
graph substrate per ADR 0008.
The MCP entry scripts (`scripts/05_mcp_server.py`,
`scripts/06_mcp_http_server.py`) select the backend at
startup via `LORE_GRAPH_BACKEND`:
```bash
# Pickle (default) — load .graph.pkl
python3 scripts/05_mcp_server.py
# or
python3 scripts/06_mcp_http_server.py
# Neo4j — connect to bolt://$LORE_NEO4J_URI
LORE_GRAPH_BACKEND=neo4j LORE_NEO4J_URI=bolt://localhost:7687 \
python3 scripts/06_mcp_http_server.py
```
Compose brings up the Neo4j stack with a profile:
```bash
# Pickle-backed MCP (slice 11 default)
docker compose --profile pickle up -d
# Neo4j-backed MCP (production substrate, slice 5)
docker compose --profile neo4j up -d
```
The Neo4j compose stack includes:
* `neo4j:5` — the database (`NEO4J_AUTH=none` for loopback;
**switch to a username/password before any non-loopback
exposure**).
* `lore-engine-ingest` — one-shot job that runs
`01_ingest.py --write-neo4j --skip-cognee` after Neo4j
is healthy.
* `lore-engine-mcp-neo4j` — the MCP HTTP server reading
from Neo4j (depends on both `neo4j` healthy and
`lore-engine-ingest` exited 0).
The pickle profile keeps working exactly as in slice 11.4
(pickup unchanged, MCP server on port 8765, baked
`.graph.pkl`).
## Run
```bash

Binary file not shown.