{"id":48347995,"url":"https://github.com/nambok/mentedb","last_synced_at":"2026-04-10T13:00:46.983Z","repository":{"id":349090877,"uuid":"1201033913","full_name":"nambok/mentedb","owner":"nambok","description":"A cognition aware database engine for AI agent memory. Purpose built in Rust with WAL, HNSW, knowledge graphs, and speculative context pre assembly. Not a wrapper, a ground up storage engine that thinks.","archived":false,"fork":false,"pushed_at":"2026-04-07T08:45:06.000Z","size":27340,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T10:03:10.368Z","etag":null,"topics":["agent-memory","ai","ai-agents","cognitive-architecture","context-window","database","knowledge-graph","langchain","llm","memory","rag","rust","storage-engine","vector-database"],"latest_commit_sha":null,"homepage":"https://mentedb.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nambok.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T05:50:14.000Z","updated_at":"2026-04-07T06:45:23.000Z","dependencies_parsed_at":"2026-04-07T10:01:10.246Z","dependency_job_id":null,"html_url":"https://github.com/nambok/mentedb","commit_stats":null,"previous_names":["nambok/mentedb"],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/nambok/mentedb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nambok%2Fmentedb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nambok%2Fmentedb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nambok%2Fmentedb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nambok%2Fmentedb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nambok","download_url":"https://codeload.github.com/nambok/mentedb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nambok%2Fmentedb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31551891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T10:21:54.569Z","status":"ssl_error","status_checked_at":"2026-04-08T10:21:38.171Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai","ai-agents","cognitive-architecture","context-window","database","knowledge-graph","langchain","llm","memory","rag","rust","storage-engine","vector-database"],"created_at":"2026-04-05T08:03:05.442Z","updated_at":"2026-04-08T11:00:30.074Z","avatar_url":"https://github.com/nambok.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MenteDB\n\n[![Crates.io](https://img.shields.io/crates/v/mentedb-core)](https://crates.io/crates/mentedb-core) [![docs.rs](https://img.shields.io/docsrs/mentedb-core)](https://docs.rs/mentedb-core) [![CI](https://github.com/nambok/mentedb/actions/workflows/ci.yml/badge.svg)](https://github.com/nambok/mentedb/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) [![npm](https://img.shields.io/npm/v/mentedb)](https://www.npmjs.com/package/mentedb) [![PyPI](https://img.shields.io/pypi/v/mentedb)](https://pypi.org/project/mentedb/)\n\n**The Mind Database for AI Agents**\n\nMenteDB is a purpose built database engine for AI agent memory. Not a wrapper around existing databases, but a ground up Rust storage engine that understands how AI/LLMs consume data.\n\n\u003e *mente* (Spanish): mind, intellect\n\n## Quick Start\n\n**Just remember a conversation:**\n\n```bash\n# Via REST API\ncurl -X POST http://localhost:6677/v1/ingest \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"conversation\": \"User: I prefer Python over JS\\nAssistant: Noted!\", \"agent_id\": \"my-agent\"}'\n\n# Response: { \"memories_stored\": 2, \"rejected_low_quality\": 5, \"contradictions\": 0 }\n```\n\n**Via MCP (Claude CLI, Copilot CLI, Cursor):**\n\n```json\n// claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"mentedb\": {\n      \"command\": \"mentedb-mcp\",\n      \"args\": [\"--data-dir\", \"~/.mentedb\"]\n    }\n  }\n}\n```\n\nThen the AI can call `ingest_conversation` directly. No manual memory structuring needed.\n\n**Embed in Rust:**\n\n```rust\nuse mentedb::MenteDb;\n\nlet db = MenteDb::open(\"./my-agent-memory\")?;\ndb.store(\u0026memory_node)?;\nlet context = db.assemble_context(agent_id, space_id, 4096)?;\n```\n\n## Why MenteDB?\n\nEvery database ever built assumes the consumer can compensate for bad data organization. **AI can't.** A transformer gets ONE SHOT, a single context window, a single forward pass. MenteDB is a *cognition preparation engine* that delivers perfectly organized knowledge because the consumer has no ability to reorganize it.\n\n### The Memory Quality Problem\n\nMost AI memory tools store everything and retrieve by similarity. The result: **context windows full of noise.** Studies show up to 97% of automatically stored memories are irrelevant.\n\nMenteDB solves this with **write time intelligence:**\n\n1. **LLM Powered Extraction** parses conversations and extracts only what matters: decisions, preferences, corrections, facts, entities\n2. **Quality Filtering** rejects low confidence extractions before they hit storage\n3. **Deduplication** checks embedding similarity against existing memories\n4. **Contradiction Detection** flags when new information conflicts with existing beliefs\n5. **Belief Propagation** cascades updates when facts change\n\nThe result: a clean, curated memory that actually helps the AI perform better.\n\n### What Makes MenteDB Different\n\n| Feature | Traditional DBs | Vector DBs | Mem0/Zep | MenteDB |\n|---------|----------------|------------|----------|---------|\n| Storage model | Tables/Documents | Embeddings | Key value | Memory nodes (embeddings + graph + temporal) |\n| Query result | Raw data | Similarity scores | Raw memories | **Token budget optimized context** |\n| Memory quality | Manual | None | LLM extract | **LLM extract + quality filter + dedup + contradiction** |\n| Understands AI attention? | No | No | No | **Yes, U curve ordering** |\n| Tracks what AI knows? | No | No | No | **Epistemic state tracking** |\n| Multi-agent isolation? | Schema level | Collection level | API key | **Memory spaces with ACLs** |\n| Updates cascade? | Foreign keys | No | No | **Belief propagation** |\n\n### Core Features\n\n- **Automatic Memory Extraction** LLM powered pipeline extracts structured memories from raw conversations\n- **Write Time Intelligence** Quality filter, deduplication, and contradiction detection at ingest\n- **Attention Optimized Context Assembly** Respects the U curve (critical data at start/end of context)\n- **Belief Propagation** When facts change, downstream beliefs are flagged for re evaluation\n- **Delta Aware Serving** Only sends what changed since last turn (40 to 60% token savings)\n- **Cognitive Memory Tiers** Working, Episodic, Semantic, Procedural, Archival\n- **Knowledge Graph** CSR/CSC graph with BFS/DFS traversal and contradiction detection\n- **Memory Spaces** Multi agent isolation with per space ACLs\n- **MQL** Mente Query Language with full boolean logic (AND, OR, NOT) and ordering (ASC/DESC)\n- **Type Safe IDs** MemoryId, AgentId, SpaceId newtypes prevent accidental mixing\n- **Binary Embeddings** Base64 encoded storage, 65% smaller than JSON arrays\n- **gRPC + REST + MCP** Three integration paths for any use case\n\n### Performance Targets (10M memories)\n\n| Operation | Target |\n|-----------|--------|\n| Point lookup | ~50ns |\n| Multi-tag filter | ~10us |\n| k-NN similarity search | ~5ms |\n| Full context assembly | \u003c50ms |\n| Startup (mmap) | \u003c1ms |\n\n## Integration Options\n\n### 1. MCP Server (AI Clients)\n\nFor Claude CLI, Copilot CLI, Cursor, Windsurf, and any MCP compatible client.\n\n```bash\ncargo install mentedb-mcp\n```\n\nSee [mentedb-mcp](https://github.com/nambok/mentedb-mcp) for setup, configuration, and the full list of tools.\n\n**10 tools available:** `store_memory`, `recall_memory`, `search_memories`, `relate_memories`, `forget_memory`, `assemble_context`, `get_stats`, `register_entity`, `get_cognitive_state`, `ingest_conversation`\n\n### 2. REST API\n\n```bash\n# Start the server\ncargo run -p mentedb-server -- --data-dir ./data --jwt-secret-file ./secret.key\n\n# Store a memory\ncurl -X POST http://localhost:6677/v1/memories \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"agent_id\": \"...\", \"content\": \"User prefers dark mode\", \"memory_type\": \"semantic\"}'\n\n# Ingest a conversation (automatic extraction)\ncurl -X POST http://localhost:6677/v1/ingest \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"conversation\": \"...\", \"agent_id\": \"...\"}'\n\n# Recall memories\ncurl -X POST http://localhost:6677/v1/query \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"mql\": \"RECALL memories WHERE tag = \\\"preferences\\\" LIMIT 10\"}'\n```\n\n### 3. gRPC\n\nBidirectional streaming for real time cognition updates. Proto file at `crates/mentedb-server/proto/mentedb.proto`.\n\n### 4. SDKs\n\n**Python:**\n```python\nfrom mentedb import MenteDb\n\ndb = MenteDb(\"./agent-memory\")\ndb.store(content=\"User prefers Python\", memory_type=\"semantic\", agent_id=\"my-agent\")\ndb.ingest(\"User: I switched to Vim\\nAssistant: Got it!\")\nresults = db.recall(\"RECALL memories WHERE tag = 'preferences' LIMIT 5\")\n```\n\n**TypeScript:**\n```typescript\nimport { MenteDb } from 'mentedb';\n\nconst db = new MenteDb('./agent-memory');\nawait db.store({ content: 'User prefers TypeScript', memoryType: 'semantic', agentId: 'my-agent' });\nawait db.ingest('User: I switched to Neovim\\nAssistant: Noted!');\nconst results = await db.recall(\"RECALL memories WHERE tag = 'editor' LIMIT 5\");\n```\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph API[\"API Layer\"]\n        MQL[\"MQL Parser\"]\n        QE[\"Query Planner\"]\n        GRPC[\"gRPC / REST / MCP\"]\n    end\n\n    subgraph Extraction[\"Memory Extraction\"]\n        LLM[\"LLM Provider\u003cbr/\u003eOpenAI / Anthropic / Ollama\"]\n        QF[\"Quality Filter\"]\n        DEDUP[\"Deduplication\"]\n        CONTRA_EX[\"Contradiction Check\"]\n    end\n\n    subgraph Cognitive[\"Cognitive Engine\"]\n        CTX[\"Context Assembly\u003cbr/\u003eU curve, delta aware\"]\n        STREAM[\"Stream Cognition\u003cbr/\u003elive push corrections\"]\n        PAIN[\"Pain Signals\u003cbr/\u003emistake aversion\"]\n        PHANTOM[\"Phantom Memories\u003cbr/\u003eknowledge gap tracking\"]\n    end\n\n    subgraph Intelligence[\"Inference Layer\"]\n        BP[\"Belief Propagation\"]\n        WI[\"Write Time Inference\"]\n        INTERF[\"Interference Detection\"]\n    end\n\n    subgraph Index[\"Index Layer\"]\n        HNSW[\"HNSW Vector Index\"]\n        ROAR[\"Roaring Bitmap Tags\"]\n        TEMP[\"Temporal Index\"]\n    end\n\n    subgraph Graph[\"Knowledge Graph\"]\n        CSR[\"CSR/CSC Storage\"]\n        TRAV[\"BFS / DFS Traversal\"]\n    end\n\n    subgraph Storage[\"Storage Engine\"]\n        BUF[\"Buffer Pool\u003cbr/\u003eCLOCK eviction\"]\n        WAL[\"Write Ahead Log\u003cbr/\u003eLZ4, crash safe\"]\n        PAGE[\"Page Manager\u003cbr/\u003e16KB pages\"]\n    end\n\n    LLM --\u003e QF --\u003e DEDUP --\u003e CONTRA_EX --\u003e WI\n\n    MQL --\u003e QE\n    GRPC --\u003e QE\n    QE --\u003e CTX\n    QE --\u003e Index\n    QE --\u003e Graph\n\n    WI --\u003e Graph\n    WI --\u003e Index\n    BP --\u003e Graph\n    INTERF --\u003e Index\n\n    Index --\u003e Storage\n    Graph --\u003e Storage\n\n    BUF --\u003e PAGE\n    WAL --\u003e PAGE\n```\n\n## Crates\n\nMenteDB is organized as a Cargo workspace with 13 crates:\n\n| Crate | Description |\n|-------|-------------|\n| `mentedb` | Facade crate, single public entry point |\n| `mentedb-core` | Types (MemoryNode, MemoryEdge), newtype IDs, errors, config |\n| `mentedb-storage` | Page based storage engine with crash safe WAL, buffer pool, LZ4 |\n| `mentedb-index` | HNSW vector index (bounded, concurrent), roaring bitmaps, temporal index |\n| `mentedb-graph` | CSR/CSC knowledge graph with BFS/DFS and contradiction detection |\n| `mentedb-query` | MQL parser with AND/OR/NOT, ASC/DESC ordering |\n| `mentedb-context` | Attention aware context assembly, U curve ordering, delta tracking |\n| `mentedb-cognitive` | Belief propagation, pain signals, phantom memories, speculative cache |\n| `mentedb-consolidation` | Temporal decay, salience updates, archival |\n| `mentedb-embedding` | Embedding provider abstraction |\n| `mentedb-extraction` | LLM powered memory extraction pipeline |\n| `mentedb-server` | REST + gRPC server with JWT auth, space ACLs, rate limiting |\n| `mentedb-replication` | Raft based replication (experimental) |\n\n## Security\n\nMenteDB includes production security features:\n\n- **JWT Authentication** on all REST and gRPC endpoints\n- **Agent Isolation** JWT claims enforce per agent data access\n- **Space ACLs** fine grained permissions for multi agent setups\n- **Admin Keys** separate admin authentication for token issuance\n- **Rate Limiting** per agent write rate enforcement\n- **Embedding Validation** dimension mismatch returns errors, not panics\n\n```bash\n# Production deployment\nexport MENTEDB_JWT_SECRET=\"your-secret-here\"\nexport MENTEDB_ADMIN_KEY=\"your-admin-key\"\nexport MENTEDB_LLM_PROVIDER=\"openai\"\nexport MENTEDB_LLM_API_KEY=\"sk-...\"\n\nmentedb-server --require-auth --data-dir /var/mentedb/data\n```\n\n## LLM Extraction Configuration\n\nConfigure the extraction pipeline via environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MENTEDB_LLM_PROVIDER` | openai, anthropic, ollama, none | none |\n| `MENTEDB_LLM_API_KEY` | API key for the provider | |\n| `MENTEDB_LLM_MODEL` | Model name | Provider default |\n| `MENTEDB_LLM_BASE_URL` | Custom base URL (Ollama, proxies) | Provider default |\n| `MENTEDB_EXTRACTION_QUALITY_THRESHOLD` | Min confidence to store (0.0 to 1.0) | 0.7 |\n| `MENTEDB_EXTRACTION_DEDUP_THRESHOLD` | Similarity threshold for dedup (0.0 to 1.0) | 0.85 |\n\n## MQL Examples\n\n```sql\n-- Vector similarity search\nRECALL memories NEAR [0.12, 0.45, 0.78, 0.33] LIMIT 10\n\n-- Boolean filters with OR and NOT\nRECALL memories WHERE type = episodic AND (tag = \"backend\" OR tag = \"frontend\") LIMIT 5\nRECALL memories WHERE NOT tag = \"archived\" ORDER BY salience DESC\n\n-- Content similarity\nRECALL memories WHERE content ~\u003e \"database migration strategies\" LIMIT 10\n\n-- Graph traversal\nTRAVERSE 550e8400-e29b-41d4-a716-446655440000 DEPTH 3 WHERE edge_type = caused\n\n-- Consolidation\nCONSOLIDATE WHERE type = episodic AND accessed \u003c \"2024-01-01\"\n```\n\n## Docker\n\n```bash\ndocker build -t mentedb .\ndocker run -p 6677:8080 \\\n  -e MENTEDB_JWT_SECRET=your-secret \\\n  -e MENTEDB_LLM_PROVIDER=openai \\\n  -e MENTEDB_LLM_API_KEY=sk-... \\\n  -v mentedb-data:/data \\\n  mentedb\n```\n\nOr with docker-compose:\n\n```bash\ndocker-compose up -d\n```\n\n## Benchmarks\n\n### Quality Benchmarks (5/5 passing)\n\n| Test | Result | Key Metric |\n|------|--------|------------|\n| Stale Belief | PASS | Superseded memories correctly excluded |\n| Delta Savings | PASS | 90.6% token reduction over 20 turns |\n| Sustained Conversation | PASS | 100 turns, 3 projects, 0% stale returns |\n| Attention Budget | PASS | U-curve ordering maintains LLM compliance |\n| Noise Ratio | PASS | 100% useful vs 80% naive, +20pp improvement |\n\n### Performance Benchmarks (Criterion)\n\n| Benchmark | 100 | 1,000 | 10,000 |\n|-----------|-----|-------|--------|\n| Insert throughput | 13ms | 243ms | 2.65s |\n| Context assembly | 218us | 342us | 696us |\n\n### Running Benchmarks\n\n```bash\n# Engine tests (no LLM required)\npython3 benchmarks/run_all.py --no-llm\n\n# Full suite (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)\npython3 benchmarks/run_all.py\n\n# Criterion performance benchmarks\ncargo bench\n```\n\n## Building\n\n```bash\ncargo build              # Build all crates\ncargo test               # Run 427+ tests\ncargo clippy             # Lint\ncargo bench              # Benchmarks\ncargo doc --open         # Documentation\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nApache 2.0, see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnambok%2Fmentedb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnambok%2Fmentedb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnambok%2Fmentedb/lists"}