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

Only HierarchicalRAGAdapter and GraphitiMemoryEngine are implemented today (infrastructure/adapters/memory/). CogneeMemoryEngine, Mem0MemoryEngine, LettaMemoryEngine, and LlamaIndexMemoryEngine are design targets — their extras are declared in pyproject.toml (and gated by the check_kb_cognee_extras_only.py CI guard so a future eager import can't leak into the base install) but no adapter class exists yet, so setting KBCorpusSpec.memory_engine.kb_alias to cognee, mem0, letta, or llamaindex will not currently resolve.

Adapter	kb_alias	Extras	Status	Primary strength	Trade-off
HierarchicalRAGAdapter	hierarchical_rag	none (default)	implemented	4-level Alpha-GPT hierarchy + Reciprocal Rank Fusion + RAPTOR summaries	AlphaSwarm-native; not bi-temporal
CogneeMemoryEngine	cognee	[cognee]	planned, not yet implemented	Tri-store (graph + vector + relational) + native EBAC + multimodal ingest	Heavy dep; LanceDB+Kuzu only for native ACL
GraphitiMemoryEngine	graphiti	[graphiti]	implemented	Temporal Graphiti episodes + hybrid recall with tenant/corpus namespaces	Neo4j required; live local-model tuning still gated
Mem0MemoryEngine	mem0	[mem0]	planned, not yet implemented	User-centric personalisation, 12-layer cognitive memory	Less structural extraction
LettaMemoryEngine	letta	[letta]	planned, not yet implemented	Full agent runtime integration	Heavy; not pure memory
LlamaIndexMemoryEngine	llamaindex	[llamaindex]	planned, not yet implemented	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.

Graphiti opt-in defaults

GraphitiMemoryEngine is registered as memory_engine/graphiti in alphaswarm_kb. Its default kwargs live in configs/memory_engines/graphiti_default.yaml and use a namespace template of tenant:{tenant_id}:corpus:{corpus_name}. Local development defaults target an Ollama-compatible OpenAI endpoint at http://localhost:11434/v1 and nomic-embed-text embeddings, while tests inject a fake client so the zero-extras suite stays hermetic.

Live operation requires installing alphaswarm-kb[graphiti], starting Neo4j, and validating the local model's structured-output behavior before enabling any scheduled maintenance workflow.

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 (the only implemented graph store today, and the default) for KBCorpusSpec.graph_store.kb_alias. falkordb and memgraph extras are declared in pyproject.toml and named as the intended migration targets, but no falkordb/memgraph adapter class exists under infrastructure/adapters/graph/ yet, so those aliases won't currently resolve. 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.