AlphaSwarm Knowledge Base

The alphaswarm_kb boundary owns AlphaSwarm's cognitive-memory layer. It extracts the historical alphaswarm/rag/ (HierarchicalRAG) and alphaswarm/llm/memory.py (RedisHybridMemory) modules into a Clean-Architecture package with a pluggable adapter trinity for memory engines, vector stores, graph stores, ACL evaluators, and policy engines.

Sub-docs

• kb-runtime.md — KBRuntime + hash-locked KBCorpusSpec
  • kb_runs ledger.
• memory-engines.md — IMemoryEngine adapter trinity (HierarchicalRAG default; Cognee / Graphiti / Mem0 / Letta / LlamaIndex opt-in).
• bi-temporal-graph.md — PermissionedDataPoint
  • four-timestamp model + invalidated_by_edge_id Graphiti-style edge invalidation.
• layer-composition.md — Four-scope precedence
  • bi-temporal merge.
• kb-permissions.md — AccessBitmap + OpenFGA + OPA + Cedar hybrid stack.
• kb-federation.md — Cross-silo marketplace federation reverse-proxy.
• kb-silo-iac.md — Terragrunt unit-per-tenant + cloud-parallel modules.
• rag.md — Extracted hierarchical RAG (Alpha-GPT four-level).
• pgvector-control-plane.md — pgvector default vector store + data.vector.* MCP tools.
• research-papers-rag.md — Math-aware paper ingest + hybrid retrieval.

At a glance

Concern	Where
Runtime	alphaswarm_kb.runtime.KBRuntime (single executor, rule 56)
Spec	alphaswarm_kb.spec.KBCorpusSpec (hash-locked, rule 57)
Registry	alphaswarm_kb.registry.persist_spec → kb_corpus_spec_versions
Composition root	alphaswarm_kb.composition_root.build_default_container
Domain ports	alphaswarm_kb.domain.ports.* (zero framework imports)
Bi-temporal envelope	alphaswarm_kb.domain.models.permissioned_datapoint.PermissionedDataPoint
Adapter metaclass	alphaswarm_kb.domain.ports.base.KBAdapterMeta (rule 58)
Agent surface	data.kb.* DataMCP tools (rule 59)
Federation	alphaswarm_kb_federation/ standalone reverse-proxy (rule 60); scaffold only today — see kb-federation.md

Why the boundary

See ADR-014 for the full rationale.

Hard rules

• 56: All KB lifecycle goes through KBRuntime.
• 57: kb_corpus_spec_versions rows are immutable.
• 58: Adapters register via KBAdapterMeta.
• 59: Agents read KB only through data.kb.* tools.
• 60: Cross-silo recall goes through alphaswarm_kb_federation only.

Migration

Legacy alphaswarm.rag.* and alphaswarm.llm.memory import paths keep working through DeprecationWarning shims for one release cycle. New code imports from alphaswarm_kb.rag.* and alphaswarm_kb.memory.* directly.

Deprecations

• Kuzu graph store — upstream archived October 2025. The alphaswarm_kb extra is kuzu-deprecated; the adapter warns on import and will be removed after one release cycle. Migrate KBCorpusSpec.graph_store.kb_alias to neo4j (the only implemented graph store today, and the default) — falkordb/memgraph are the named migration targets but have no adapter implementation yet. See memory-engines.md.