A second brain for AI agents — episodic, semantic, and procedural memory in one engine.

Quick Start · Architecture · Why CogDB · Roadmap · Research

---

🧠 The Problem

Every AI agent framework treats memory as someone else's problem.

You bolt on a vector database. Then a graph DB for relationships. Then SQLite for structured stuff. Now you're maintaining three backends that don't talk to each other. When two agents update the same fact at the same time, things break silently.

CogDB is a single database that gives AI agents a complete memory system. One install, one interface, one data store.

🌱 What CogDB Does Differently

CogDB unifies the three types of memory that map to how human cognition actually works:

🟢 Episodic What happened Timestamped records of agent interactions, observations, and tool calls. Stored as vector embeddings with full metadata. Agents search by similarity — "find me situations like this one."

🟢 Semantic What is known A temporal knowledge graph where facts have lifecycles. Facts get superseded automatically when newer ones contradict them. Confidence scores, validity windows, provenance links.

🟢 Procedural How to do things Learned workflows captured from successful agent task completions. Reusable templates with success tracking. This memory type basically doesn't exist in any other system.

⚡ Why CogDB

Capability	Mem0	Zep	Letta	MemPalace	CogDB
Episodic memory	✓	✓	✓	✓	✓
Semantic / knowledge graph	✓	✓	✓	✓	✓
Procedural memory	⚠️	✗	⚠️	✗	✓
Token-aware retrieval	✗	✗	✗	⚠️	✓
Multi-agent memory scopes	scoped	per-user	shared	per-agent	4 formal scopes
Single unified engine	✗	✗	✗	✗	✓
MCP server	✗	✗	✗	✓	✓
AutoGen + LangGraph adapters	partial	✗	✗	✗	✓
CrewAI adapter	✗	✗	✗	✗	✓
OpenAI Agents SDK adapter	✗	✗	✗	✗	✓
Semantic Kernel adapter	✗	✗	✗	✗	✓
LlamaIndex adapter	✗	✗	✗	✗	✓
Schema migration tooling	✗	✗	✗	✗	✓

🏗 Architecture

Four layers, one engine:

• Layer 1 — Agent Interface. Drop-in adapters for AutoGen, LangGraph, CrewAI, OpenAI Agents SDK, Semantic Kernel, and LlamaIndex. MCP server so any MCP-compatible agent can connect. Native Python SDK.
• Layer 2 — Query Planner. Token-aware retrieval routes queries across stores and packs results into the budget you set. Highest importance first, nothing wasted.
• Layer 3 — Cognitive Pipeline. Encoding, storage, consolidation, retrieval, and decay. Memories don't just sit there — they evolve.
• Layer 4 — Tri-Memory Store. Episodic (vector embeddings), semantic (temporal knowledge graph), procedural (workflow templates). Three stores, one query interface.

🚀 Quick Start

pip install git+https://github.com/MuLIAICHI/cogdb.git

from cogdb import CognitiveDB

db = CognitiveDB(db_path="./agent_memory")

# 🟢 Store an episodic memory
db.remember(
    "Deployed v2.3 to production. CORS error on /users endpoint.",
    agent_id="devops-agent",
    importance=0.9,
)

# 🟢 Store a semantic fact (gets superseded automatically when contradicted)
db.learn(
    subject="api_service",
    predicate="version",
    object="v2.3",
    agent_id="devops-agent",
    confidence=1.0,
)

# 🟢 Store a procedural workflow
db.learn_procedure(
    name="fix_cors_error",
    steps=[
        {"action": "check_nginx_config", "tool": "cat /etc/nginx/conf.d/api.conf"},
        {"action": "add_cors_headers", "tool": "sed"},
        {"action": "reload_nginx", "tool": "systemctl reload nginx"},
        {"action": "verify", "tool": "curl -I"},
    ],
    agent_id="devops-agent",
    applicable_contexts=["cors", "nginx", "api"],
)

# 🟢 Recall with a token budget
memories = db.recall(
    "How do we fix CORS errors?",
    agent_id="devops-agent",
    token_budget=500,
)

# 🟢 Get progressive context (L0 → L3)
context = db.get_context(
    agent_id="devops-agent",
    level=2,
    task_hint="API gateway returning 403 on preflight",
    token_budget=800,
)

🔌 Integrations

🟢 AutoGen from cogdb.adapters.autogen import CogDBMemory from autogen_agentchat.agents import AssistantAgent memory = CogDBMemory(db_path="./memory") agent = AssistantAgent( name="assistant", memory=[memory], ) Drop-in replacement for AutoGen's basic ListMemory.	🟢 LangGraph from cogdb.adapters.langgraph import ( CogDBCheckpointer, CogDBStore, ) graph = StateGraph(State).compile( checkpointer=CogDBCheckpointer(...), store=CogDBStore(...), ) Native BaseCheckpointSaver and BaseStore implementations.	🟢 MCP Server cogdb-mcp --db-path ./memory Exposes 6 tools — remember, recall, learn, learn_procedure, get_context, forget — to any MCP-compatible agent (Claude Code, Cursor, Windsurf).
🟢 CrewAI from cogdb.adapters.crewai import CogDBCrewAIStorage memory = CogDBCrewAIStorage( agent_id="my-crew-agent", db_path="./memory", ) # Pass to CrewAI agent via memory_config Drop-in Storage implementation for CrewAI agents.	🟢 OpenAI Agents SDK from cogdb.adapters.openai_agents import ( CogDBAgentMemory, make_memory_tools, ) mem = CogDBAgentMemory(agent_id="my-agent") tools = make_memory_tools(mem) # Add tools to your Agent Exposes remember, recall, and get_context as agent tools.	🟢 Semantic Kernel from cogdb.adapters.semantic_kernel import CogDBMemoryStore store = CogDBMemoryStore( agent_id="sk-agent", db_path="./memory", ) # Use as SK MemoryStoreBase Full async MemoryStoreBase implementation.
🟢 LlamaIndex from cogdb.adapters.llamaindex import CogDBChatMemory memory = CogDBChatMemory.from_defaults( agent_id="li-agent", db_path="./memory", ) # Use as LlamaIndex BaseMemory BaseMemory + CogDBVectorIndex for chat and retrieval agents.	🟢 Schema Migration from cogdb.schema.migration import SchemaMigration from cogdb.schema import FieldSchema migration = ( SchemaMigration(agent_id="my-agent", from_version=1, to_version=2) .add_field("priority", FieldSchema(type="int"), default=0) .rename_field("tags", "labels") ) db.migrate_schema(migration) Safe versioned schema evolution with metadata backfill.

📊 Token-Aware Retrieval

This is the part that took the most iteration. Most memory systems dump a wall of context into the LLM and hope for the best. CogDB does it in tiers:

┌─ Token Budget: 500 ──────────────────────────────────┐
│                                                       │
│  L0  Identity              ~50 tokens     [filled]    │
│  L1  Critical facts       ~200 tokens     [filled]    │
│  L2  Task-relevant        ~250 tokens     [filled]    │
│  L3  Deep search             0 tokens     [skipped]   │
│                                                       │
└───────────────────────────────────────────────────────┘

Set a budget, CogDB fills it from the top with the highest-importance memories that fit. The agent gets exactly what it needs and nothing it doesn't — which means faster responses, lower API costs, and no context window blowouts.

👥 Multi-Agent Memory Scopes

When you have multiple agents working together, they need different levels of memory access. CogDB has four formal scopes with consistency guarantees:

┌─────────────────────────────────────────────┐
│  🟢 Organization      All agents read       │
│  ┌─────────────────────────────────────┐    │
│  │  🟢 Team        Group read-write    │    │
│  │  ┌─────────────────────────────┐    │    │
│  │  │  🟢 Private   Single agent  │    │    │
│  │  └─────────────────────────────┘    │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│  🟢 Session  Ephemeral, auto-deleted        │
└─────────────────────────────────────────────┘

Contradiction detection runs at write time. Conflict resolution handles concurrent writes. No silent data loss when agents collaborate.

🗺 Roadmap

• ✅ Phase 0 — Python PoC v0.2.0 — Tri-memory engine, pipeline, AutoGen + LangGraph + MCP adapters.
• ✅ Phase 1 — Rust Engine v0.3.0 — Purpose-built storage with HNSW, WAL, crash recovery, PyO3 bindings.
• ✅ Phase 2 — ML Retrieval v0.4.0 — Learned importance model, HNSW rank blending, tokenised procedure search. Suite 1 benchmark: 90.7 / 100.
• ✅ Phase 3A — Typed Schemas — Dynamic metadata schemas, per-agent validation, strict/non-strict modes.
• ✅ Phase 3C — Schema Migration — Versioned add/rename/drop/change_type with metadata backfill. db.migrate_schema().
• ✅ Adapters expansion — CrewAI, OpenAI Agents SDK, Semantic Kernel, LlamaIndex. 6 framework adapters total.
• 🔄 Phase 3B — Metadata Indexing (next) — SQLite indexes on queried metadata keys (requires Rust store changes).
• 📋 Phase 4 — Distributed — Clustered WAL replication, multi-node deployment.

📚 Research

CogDB is grounded in academic research on cognitive architectures, learned database systems, and multi-agent memory:

• CoALA (Sumers, Yao et al., 2024) — Cognitive Architectures for Language Agents
• JEPA (LeCun, 2022) — A Path Towards Autonomous Machine Intelligence
• Learned Index Structures (Kraska et al., 2018) — Neural networks replacing B-Trees
• Multi-Agent Memory Architecture (UCSD, 2026) — Cache coherence for agent memory

Full landscape analysis covering 15+ existing systems → docs/research.md

🤝 Contributing

CogDB is in early development and contributions are welcome across:

• Framework adapters — LlamaIndex plugins, custom integrations
• Benchmarks — LongMemEval, comparison vs Mem0/Zep
• Core engine — Memory consolidation, importance scoring, retrieval
• Research — New memory system analyses, academic paper reviews

See CONTRIBUTING.md to get started.

📄 License

MIT — see LICENSE.

📖 Citation

If you use CogDB in research or production:

@software{cogdb2026,
  title  = {CogDB: A Cognitive Database for AI Agents},
  author = {Mustapha Liaichi},
  year   = {2026},
  url    = {https://github.com/MuLIAICHI/cogdb}
}

---

Built by Mustapha Liaichi · AYAutomate

_{If CogDB saves you from stitching together three databases, ⭐ the repo.}