Igor Lins e Silva
f20a1a30fe
Part of #875. Bring the VitePress site into line with the new README and the reproducibility scorecard: drop category-error comparisons, drop retracted claims, retain only metrics and caveats that survive audit. website/index.md - New tagline matches README (local-first, verbatim, pluggable backend, 96.6% R@5 raw, zero API calls). - Replace the "MemPalace hybrid 100% / Supermemory ~99% / Mastra 94.87% / Mem0 ~85%" comparison table with a single honest table showing MemPalace's own retrieval-recall numbers (raw 96.6%, hybrid v4 held-out 98.4%). Add an explicit sentence explaining why we no longer publish a cross-system table on the landing page (retrieval recall vs QA accuracy are different metrics). - Soften the "ChromaDB-powered vector search" feature blurb to be backend-agnostic, since the retrieval layer is pluggable. website/reference/benchmarks.md - Full rewrite of the retrieval-recall tables. No more "100%" headline; honest held-out 98.4% R@5 replaces it. Added the model-agnostic rerank result (99.2% R@5 / 100% R@10 with minimax-m2.7 via Ollama) to show the pipeline is not Haiku-specific. - Drop the LoCoMo "Hybrid v5 + Sonnet rerank (top-50) 100%" row. With per-conversation session counts of 19-32 and top_k=50, the retrieval stage returns every session by construction — the number measures an LLM's reading comprehension, not retrieval. - Drop the cross-system comparison tables. Link out to each project's own research page (Mastra, Mem0, Supermemory) for their published numbers and metric definitions. - Rewrite reproduction commands to use the correct repository and demonstrate the new --llm-backend ollama flag. website/concepts/the-palace.md - Remove the "+34%" row / paragraph. Wing/room filtering is standard metadata filtering in the vector store, not a novel retrieval mechanism — the April-7 note already retracted that framing; this finishes the retraction on the website where it had remained. website/guide/searching.md - Same treatment for "34% retrieval improvement". Reframe as operational scoping, not a novel boost. website/reference/contributing.md - Update the "palace structure matters" bullet to reflect the same framing: scoping-not-magic. website/concepts/knowledge-graph.md - Replace the MemPalace-vs-Zep feature matrix with a short "related work" note that links to Zep's own documentation for authoritative details on their deployment model. Avoids claims we cannot verify at source.
91 lines
2.7 KiB
Markdown
91 lines
2.7 KiB
Markdown
# Knowledge Graph
|
|
|
|
MemPalace includes a temporal entity-relationship graph — like Zep's Graphiti, but SQLite instead of Neo4j. Local and free.
|
|
|
|
## What It Stores
|
|
|
|
Entity-relationship triples with temporal validity:
|
|
|
|
```
|
|
Subject → Predicate → Object [valid_from → valid_to]
|
|
```
|
|
|
|
Facts have time windows. When something stops being true, you invalidate it — and historical queries still find it.
|
|
|
|
## Usage
|
|
|
|
### Python API
|
|
|
|
```python
|
|
from mempalace.knowledge_graph import KnowledgeGraph
|
|
|
|
kg = KnowledgeGraph()
|
|
|
|
# Add facts
|
|
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
|
|
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
|
|
kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")
|
|
|
|
# Query: everything about Kai
|
|
kg.query_entity("Kai")
|
|
# → [Kai → works_on → Orion (current), Kai → recommended → Clerk (2026-01)]
|
|
|
|
# Query: what was true in January?
|
|
kg.query_entity("Maya", as_of="2026-01-20")
|
|
# → [Maya → assigned_to → auth-migration (active)]
|
|
|
|
# Timeline
|
|
kg.timeline("Orion")
|
|
# → chronological story of the project
|
|
```
|
|
|
|
### Invalidating Facts
|
|
|
|
When something stops being true:
|
|
|
|
```python
|
|
kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")
|
|
```
|
|
|
|
Now queries for Kai's current work won't return Orion. Historical queries still will.
|
|
|
|
### MCP Tools
|
|
|
|
Through the MCP server, the knowledge graph is available as tools:
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `mempalace_kg_query` | Query entity relationships with time filtering |
|
|
| `mempalace_kg_add` | Add facts |
|
|
| `mempalace_kg_invalidate` | Mark facts as ended |
|
|
| `mempalace_kg_timeline` | Chronological entity story |
|
|
| `mempalace_kg_stats` | Graph overview |
|
|
|
|
## Storage
|
|
|
|
The knowledge graph uses SQLite with two tables:
|
|
|
|
**`entities`** — people, projects, tools, concepts:
|
|
- `id` — lowercase normalized name
|
|
- `name` — display name
|
|
- `type` — person, project, tool, concept, etc.
|
|
- `properties` — JSON blob for extra metadata
|
|
|
|
**`triples`** — relationships between entities:
|
|
- `subject` → `predicate` → `object`
|
|
- `valid_from` — when this became true
|
|
- `valid_to` — when it stopped being true (NULL = still current)
|
|
- `confidence` — 0.0 to 1.0
|
|
- `source_closet` — link back to the verbatim memory
|
|
|
|
Database location: `~/.mempalace/knowledge_graph.sqlite3`
|
|
|
|
## Related Work
|
|
|
|
Temporal entity-relationship graphs are a familiar pattern — Zep's
|
|
Graphiti, for example, also exposes a bi-temporal model. MemPalace's
|
|
knowledge graph is local-first (SQLite, everything on disk) and free;
|
|
Zep is a managed service backed by Neo4j with its own pricing, SLAs,
|
|
and compliance surface. See Zep's own [documentation](https://www.getzep.com/)
|
|
for authoritative details on their deployment model.
|