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:
55
README.md
55
README.md
@@ -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.
Reference in New Issue
Block a user