IMemoryEngine adapter trinity

IMemoryEngine is the vendor-neutral memory control plane. Cognee's v1.0 surface (remember / recall / improve / forget) is the canonical contract; every adapter translates at its boundary.

Comparison

Adapter	kb_alias	Extras	Primary strength	Trade-off
HierarchicalRAGAdapter	hierarchical_rag	none (default)	4-level Alpha-GPT hierarchy + Reciprocal Rank Fusion + RAPTOR summaries	AlphaSwarm-native; not bi-temporal
CogneeMemoryEngine	cognee	[cognee]	Tri-store (graph + vector + relational) + native EBAC + multimodal ingest	Heavy dep; LanceDB+Kuzu only for native ACL
GraphitiMemoryEngine	graphiti	[graphiti]	Bi-temporal edges, sub-300ms p95, no runtime LLM calls	Neo4j only
Mem0MemoryEngine	mem0	[mem0]	User-centric personalisation, 12-layer cognitive memory	Less structural extraction
LettaMemoryEngine	letta	[letta]	Full agent runtime integration	Heavy; not pure memory
LlamaIndexMemoryEngine	llamaindex	[llamaindex]	General-purpose vector backbone, big plugin ecosystem	No native temporal model

Choosing an engine

Default to hierarchical_rag unless a corpus has a specific need:

• Bi-temporal facts that change over time (CEO succession, deal status) → graphiti.
• User-scoped personalisation that needs cross-session identity → mem0.
• Multimodal pipelines with heavy LLM-driven entity extraction + cross-store coherence → cognee.
• General-purpose document QA with the LlamaIndex plugin ecosystem → llamaindex.

Switching engines

Set KBCorpusSpec.memory_engine.kb_alias and re-snapshot. The KBRuntime picks up the new adapter on the next call. The previous spec version stays in kb_corpus_spec_versions so any in-flight recall against the old version can replay.

Graph-store note: Kuzu is deprecated

Upstream Kuzu was archived in October 2025 and receives no further releases. The alphaswarm_kb extra was renamed kuzu -> kuzu-deprecated, and importing alphaswarm_kb.infrastructure.adapters.graph.kuzu_deprecated emits a DeprecationWarning. New corpora MUST choose neo4j (default), falkordb, or memgraph for KBCorpusSpec.graph_store.kb_alias; the deprecated extra exists only to keep legacy corpora readable during migration and will be removed after one release cycle. This also constrains CogneeMemoryEngine's native-ACL tri-store mode (LanceDB + Kuzu) — prefer the OpenFGA/OPA permission stack instead (kb-permissions.md).

Adding a new adapter

1. Subclass IMemoryEngine under alphaswarm_kb/src/alphaswarm_kb/infrastructure/adapters/memory/.
2. Set kb_kind = "memory_engine" + kb_alias = "your_alias". The KBAdapterMeta metaclass auto-registers (rule 58).
3. Add the optional dep to alphaswarm_kb/pyproject.toml extras.
4. Add a default-kwargs YAML under alphaswarm_kb/configs/memory_engines/your_alias_default.yaml.
5. Wire the eager import behind contextlib.suppress(Exception) in alphaswarm_kb/src/alphaswarm_kb/__init__.py.