{"id":45533378,"url":"https://github.com/agentralabs/agentic-memory","last_synced_at":"2026-02-25T03:01:04.396Z","repository":{"id":339380685,"uuid":"1161257906","full_name":"agentralabs/agentic-memory","owner":"agentralabs","description":"Persistent cognitive graph memory for AI agents — facts, decisions, reasoning chains, corrections. 16 query types, sub-millisecond. Rust core + Python SDK + MCP server.","archived":false,"fork":false,"pushed_at":"2026-02-24T05:49:48.000Z","size":2936,"stargazers_count":2,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T06:34:49.522Z","etag":null,"topics":["agent-memory","agentic","ai-agents","belief-revision","binary-format","claude","cognitive-architecture","cursor","graph-database","knowledge-graph","llm","mcp","memory","model-context-protocol","python","rust"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/agentic-memory","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentralabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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},"funding":{"github":["xeo-labs"]}},"created_at":"2026-02-18T22:53:48.000Z","updated_at":"2026-02-24T05:49:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"849e01e9-3c88-4b5f-8b7f-4df2e967a01a","html_url":"https://github.com/agentralabs/agentic-memory","commit_stats":null,"previous_names":["agentic-revolution/agentic-memory","xeo-labs/agentic-memory","agentralabs/agentic-memory"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/agentralabs/agentic-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentralabs%2Fagentic-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentralabs%2Fagentic-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentralabs%2Fagentic-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentralabs%2Fagentic-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentralabs","download_url":"https://codeload.github.com/agentralabs/agentic-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentralabs%2Fagentic-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29809137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T22:43:48.403Z","status":"online","status_checked_at":"2026-02-25T02:00:07.329Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","agentic","ai-agents","belief-revision","binary-format","claude","cognitive-architecture","cursor","graph-database","knowledge-graph","llm","mcp","memory","model-context-protocol","python","rust"],"created_at":"2026-02-23T01:30:23.608Z","updated_at":"2026-02-25T03:01:04.378Z","avatar_url":"https://github.com/agentralabs.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/github-hero-pane.svg\" alt=\"AgenticMemory hero pane\" width=\"980\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#install\"\u003e\u003cimg src=\"https://img.shields.io/badge/pip_install-agentic--brain-3B82F6?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"pip install\"\u003e\u003c/a\u003e\n  \u003ca href=\"#install\"\u003e\u003cimg src=\"https://img.shields.io/badge/cargo_install-agentic--memory-F59E0B?style=for-the-badge\u0026logo=rust\u0026logoColor=white\" alt=\"cargo install\"\u003e\u003c/a\u003e\n  \u003ca href=\"#mcp-server\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP_Server-agentic--memory--mcp-10B981?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMiAydjIwTTIgMTJoMjAiLz48L3N2Zz4=\u0026logoColor=white\" alt=\"MCP Server\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003ca href=\"paper/paper-i-format/agenticmemory-paper.pdf\"\u003e\u003cimg src=\"https://img.shields.io/badge/Research-Paper_I-8B5CF6?style=for-the-badge\" alt=\"Research Paper I\"\u003e\u003c/a\u003e\n  \u003ca href=\"paper/paper-ii-query-expansion/agenticmemory-query-expansion.pdf\"\u003e\u003cimg src=\"https://img.shields.io/badge/Research-Paper_II-8B5CF6?style=for-the-badge\" alt=\"Research Paper II\"\u003e\u003c/a\u003e\n  \u003ca href=\"paper/paper-iii-mcp-server/agentic-memory-mcp-paper.pdf\"\u003e\u003cimg src=\"https://img.shields.io/badge/Research-Paper_III-8B5CF6?style=for-the-badge\" alt=\"Research Paper III\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e · \u003ca href=\"#why-agentic-memory\"\u003eWhy\u003c/a\u003e · \u003ca href=\"#mcp-server\"\u003eMCP Server\u003c/a\u003e · \u003ca href=\"#benchmarks\"\u003eBenchmarks\u003c/a\u003e · \u003ca href=\"#the-query-engine\"\u003eQuery Engine\u003c/a\u003e · \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e · \u003ca href=\"docs/api-reference.md\"\u003eAPI\u003c/a\u003e · \u003ca href=\"paper/paper-i-format/agenticmemory-paper.pdf\"\u003ePapers\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Every AI agent has amnesia.\n\nClaude forgets your last conversation. GPT doesn't know what you decided last week. Your copilot can't recall the architecture discussions from three months ago. **Every session starts from zero.**\n\nThe current fixes don't work. Vector databases lose all structure -- you get \"similar text,\" never *\"why did I decide this?\"*. Markdown files are slow and break at scale. Key-value stores are flat -- no relationships, no reasoning chains. Provider memory is locked to one vendor.\n\n**AgenticMemory** stores your agent's knowledge as a navigable graph in a single binary file. Not \"search your old conversations.\" Your agent has a **brain** -- facts, decisions, reasoning chains, corrections, and skills -- all connected, all queryable in microseconds.\n\n```python\nfrom agentic_memory import Brain\n\nbrain = Brain(\"my_agent.amem\")\n\n# Your agent learns\nbrain.add_fact(\"User is a senior Rust developer\", session=1, confidence=0.95)\nbrain.add_decision(\"Recommended tokio for async -- team has no Go experience\", session=1)\n\n# Session 47 -- months later, different LLM, same brain:\nresults  = brain.search(\"async runtime\")          # Hybrid BM25 + vector search\nchain    = brain.traverse(decision_id)             # Why did I decide this?\ncurrent  = brain.resolve(old_fact_id)              # What's the latest version?\nreport   = brain.revise(\"Team now knows Go\")       # If this is true, what breaks?\ngaps     = brain.gaps()                            # Where am I guessing?\ntimeline = brain.drift(\"programming languages\")    # How has this belief changed?\n```\n\nOperational reliability commands (CLI):\n\n```bash\namem quality my_agent.amem\namem runtime-sync my_agent.amem --workspace . --write-episode\n```\n\nSix lines. Sixteen query types. One file holds everything. Works with Claude, GPT, Ollama, or any LLM you switch to next.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/github-terminal-pane.svg\" alt=\"AgenticMemory terminal pane\" width=\"980\"\u003e\n\u003c/p\u003e\n\n---\n\n\u003ca name=\"benchmarks\"\u003e\u003c/a\u003e\n\n## Benchmarks\n\nRust core. Memory-mapped I/O. Zero-copy access. Real numbers from Criterion statistical benchmarks:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/benchmark-chart.svg\" alt=\"Performance benchmarks\" width=\"800\"\u003e\n\u003c/p\u003e\n\n| Operation | Time | Scale |\n|:---|---:|:---|\n| Add node | **276 ns** | 10K graph |\n| Add edge | **1.2 ms** | 10K graph |\n| Traverse depth-5 | **3.4 ms** | 100K nodes |\n| Similarity search (top 10) | **9.0 ms** | 100K nodes |\n| BM25 text search (fast path) | **1.58 ms** | 100K nodes |\n| BM25 text search (slow path) | **122 ms** | 100K nodes |\n| Hybrid search (BM25 + vector) | **10.83 ms** | 100K nodes |\n| PageRank convergence | **34.3 ms** | 100K nodes |\n| Bidirectional BFS shortest path | **104 us** | 100K nodes |\n| Belief revision (cascade) | **53.4 ms** | 100K nodes |\n| Drift detection | **68.4 ms** | 100K nodes |\n| Read 10K nodes from file | **3.7 ms** | -- |\n| mmap node access | **370 ns** | 100K nodes |\n\n\u003e All v0.2 query benchmarks measured with Criterion (100 samples) on Apple M4 Pro, 64 GB, Rust 1.90.0 `--release`. Computationally intensive queries (gap detection 297s, analogical 229s, consolidation 43.6s at 100K) are designed for periodic/offline execution and complete in \u003c3s at 10K nodes.\n\n**Capacity:** A year of daily use produces a ~24 MB file. A decade fits in ~240 MB. A lifetime of memory fits in under 1 GB.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eComparison with existing systems\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n| | Vector DB | Markdown Files | Key-Value Store | **AgenticMemory** |\n|:---|:---:|:---:|:---:|:---:|\n| Storage / 10K events | ~500 MB | ~200 MB | ~50 MB | **~8 MB** |\n| Query latency (p99) | ~50 ms | ~200 ms | ~30 ms | **\u003c1 ms** |\n| Relationship tracking | None | None | None | **7 typed edges** |\n| Query types | 1 (similarity) | 1 (keyword) | 1 (key lookup) | **16** |\n| Portability | Vendor-locked | File-based | API-locked | **Single file** |\n| External dependencies | Cloud service | Embedding API | Cloud service | **None** |\n| Reconstruct reasoning | No | No | No | **Yes** |\n| Self-correction history | No | No | Partial | **Yes** |\n| \"What breaks if X changes?\" | No | No | No | **Yes** |\n| \"Where am I guessing?\" | No | No | No | **Yes** |\n\n\u003c/details\u003e\n\n---\n\n\u003ca name=\"why-agentic-memory\"\u003e\u003c/a\u003e\n\n## Why AgenticMemory\n\n**Memory is a graph, not a search index.** When you remember *why* you made a decision, you traverse a chain: decision \u003c- caused by \u003c- these facts \u003c- inferred from \u003c- observations. That's graph navigation. Vector similarity search can never reconstruct this.\n\n**One file. Truly portable.** Your entire memory is a single `.amem` file. Copy it. Back it up. Version control it. No cloud service, no API keys, no vendor lock-in.\n\n**Any LLM, any time.** Start with Claude today. Switch to GPT tomorrow. Move to a local model next year. Same brain file. [Cross-provider validation report](validation/cross-provider-report.md) with 21 interoperability tests.\n\n**Self-correcting.** Corrections don't delete -- they SUPERSEDE. The old fact, the new fact, and the correction chain are all preserved. `brain.resolve(old_id)` always returns the current truth.\n\n**Sixteen query types.** Not just search. Traversal, pattern matching, temporal comparison, causal impact, similarity, BM25 text search, hybrid search, graph centrality, shortest path, belief revision, reasoning gap detection, analogical reasoning, consolidation, drift detection, context extraction, and resolve. Five of these [don't exist anywhere else](#novel-queries).\n\n---\n\n\u003ca name=\"the-query-engine\"\u003e\u003c/a\u003e\n\n## The Query Engine\n\nSixteen ways to navigate a cognitive graph. Seven are foundational. Four are established algorithms adapted for cognitive graphs. **Five are genuinely novel -- they don't exist in any other system.**\n\n| # | Query | What it answers |\n|:--|:------|:----------------|\n| 1 | **Traversal** | \"Why did I decide this?\" -- walk reasoning chains |\n| 2 | **Pattern** | \"Show me all low-confidence decisions from last week\" |\n| 3 | **Temporal** | \"What changed between session 5 and session 20?\" |\n| 4 | **Impact** | \"What depends on this fact?\" |\n| 5 | **Similarity** | \"What else do I know about this topic?\" |\n| 6 | **Context** | \"Give me everything around this node\" |\n| 7 | **Resolve** | \"What's the current truth after corrections?\" |\n| 8 | **BM25 Search** | \"Find memories containing these exact terms\" (1.58 ms @ 100K) |\n| 9 | **Hybrid Search** | BM25 + vector fusion via RRF (10.83 ms @ 100K) |\n| 10 | **Centrality** | \"What are my foundational beliefs?\" -- PageRank (34.3 ms @ 100K) |\n| 11 | **Shortest Path** | \"How are these two ideas connected?\" -- BFS in 104 us |\n| 12 | **Belief Revision** | \"If I learn X, what breaks?\" -- counterfactual cascade |\n| 13 | **Reasoning Gaps** | \"Where am I guessing?\" -- 5 gap categories |\n| 14 | **Analogical** | \"I've solved something like this before\" -- structural fingerprints |\n| 15 | **Consolidation** | \"Clean up: dedup, link contradictions, promote inferences\" |\n| 16 | **Drift Detection** | \"How has my understanding of this topic evolved?\" |\n\n\u003ca name=\"novel-queries\"\u003e\u003c/a\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eThe five novel queries -- what makes them different\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**Belief Revision** -- Counterfactual propagation. Inject a hypothetical fact, trace every causal edge forward, report what gets invalidated. Read-only -- nothing changes until you say so. Only possible because of typed causal edges + confidence scores.\n\n```python\nreport = brain.revise(\"Team now knows Go\")\n# report.contradicted -\u003e [\"Team has no Go experience\"]\n# report.invalidated_decisions -\u003e [\"Chose Rust because no Go\"]\n# report.total_affected -\u003e 5 nodes\n```\n\n**Reasoning Gaps** -- Structural health audit. Finds decisions with no recorded justification, inferences built on a single fragile fact, high-impact nodes with low confidence, and correction chains that keep changing.\n\n```python\nreport = brain.gaps()\n# report.health_score -\u003e 0.73\n# report.gaps -\u003e [UnjustifiedDecision(...), SingleSourceInference(...), ...]\n```\n\n**Analogical Reasoning** -- Subgraph pattern matching. Finds past situations with the same reasoning *structure* even if the domain is completely different. A monolith-to-microservices migration matches a previous Flask-to-FastAPI migration -- same shape, different content.\n\n**Consolidation** -- Brain maintenance. Deduplicates near-identical facts, detects unlinked contradictions, promotes stable inferences to facts. Dry-run by default. Automatic backup before any mutation.\n\n**Drift Detection** -- Belief trajectory tracking. Shows how knowledge about a topic evolved session by session, computes stability scores, and identifies areas of active revision.\n\n```python\nreport = brain.drift(\"preferred language\")\n# Timeline: Python (session 1) -\u003e Rust (session 15) -\u003e exploring Zig (session 30)\n# report.stability -\u003e 0.3 (low -- keeps changing)\n```\n\n\u003c/details\u003e\n\n---\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n\n## Install\n\n**One-liner** (desktop profile, backwards-compatible):\n```bash\ncurl -fsSL https://agentralabs.tech/install/memory | bash\n```\n\nDownloads a pre-built `agentic-memory-mcp` binary to `~/.local/bin/` and merges the MCP server into your Claude Desktop and Claude Code configs. Memory defaults to `~/.brain.amem`. Requires `curl` and `jq`.\nIf release artifacts are not available, the installer automatically falls back to `cargo install --git` source install.\n\n**Environment profiles** (one command per environment):\n```bash\n# Desktop MCP clients (auto-merge Claude Desktop + Claude Code when detected)\ncurl -fsSL https://agentralabs.tech/install/memory/desktop | bash\n\n# Terminal-only (no desktop config writes)\ncurl -fsSL https://agentralabs.tech/install/memory/terminal | bash\n\n# Remote/server hosts (no desktop config writes)\ncurl -fsSL https://agentralabs.tech/install/memory/server | bash\n```\n\n| Channel | Command | Result |\n|:---|:---|:---|\n| GitHub installer (official) | `curl -fsSL https://agentralabs.tech/install/memory \\| bash` | Installs release binaries when available, otherwise source fallback; merges MCP config |\n| GitHub installer (desktop profile) | `curl -fsSL https://agentralabs.tech/install/memory/desktop \\| bash` | Explicit desktop profile behavior |\n| GitHub installer (terminal profile) | `curl -fsSL https://agentralabs.tech/install/memory/terminal \\| bash` | Installs binaries only; no desktop config writes |\n| GitHub installer (server profile) | `curl -fsSL https://agentralabs.tech/install/memory/server \\| bash` | Installs binaries only; server-safe behavior |\n| crates.io paired crates (official) | `cargo install agentic-memory agentic-memory-mcp` | Installs `amem` and `agentic-memory-mcp` |\n| PyPI (SDK + installer) | `pip install agentic-brain` / `pip install amem-installer` | Python SDK and auto-connector tools |\n\n### Server auth and artifact sync\n\nFor cloud/server runtime:\n\n```bash\nexport AGENTIC_TOKEN=\"$(openssl rand -hex 32)\"\n```\n\nAll MCP clients must send `Authorization: Bearer \u003csame-token\u003e`.\nIf `.amem/.acb/.avis` files are on another machine, sync them to the server first.\n\n| Goal | Command |\n|:---|:---|\n| **Just give me memory** | Run the one-liner above |\n| **Python developer** | `pip install agentic-brain` |\n| **Rust developer** | `cargo install agentic-memory-mcp` |\n| **Connect all AI tools** | `pip install amem-installer \u0026\u0026 amem-install install --auto` |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDetailed install options\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**Python SDK** (requires `amem` Rust binary -- see [INSTALL.md](INSTALL.md)):\n```bash\npip install agentic-brain\npip install agentic-brain[anthropic]   # Claude\npip install agentic-brain[openai]      # GPT\npip install agentic-brain[ollama]      # Local models\npip install agentic-brain[all]         # Everything\n```\n\n**Rust:**\n```bash\ncargo install agentic-memory           # Core CLI (amem)\ncargo install agentic-memory-mcp       # MCP server\n```\n\n\u003c/details\u003e\n\n## Deployment Model\n\n- **Standalone by default:** AgenticMemory is independently installable and operable. Integration with AgenticVision or AgenticCodebase is optional, never required.\n- **Autonomic operations by default:** runtime maintenance uses safe profile-based defaults with backup, sleep-cycle upkeep, migration safeguards, and health-ledger snapshots.\n\n| Area | Default behavior | Controls |\n|:---|:---|:---|\n| Autonomic profile | Local-first conservative posture | `AMEM_AUTONOMIC_PROFILE=desktop|cloud|aggressive` |\n| Sleep-cycle maintenance | Decay refresh, tier balancing, completed-session auto-archive | `AMEM_SLEEP_CYCLE_SECS`, `AMEM_SLEEP_IDLE_SECS` |\n| Backup + retention | Rolling backups with bounded retention | `AMEM_AUTO_BACKUP_SECS`, `AMEM_AUTO_BACKUP_RETENTION`, `AMEM_AUTO_BACKUP_DIR` |\n| Storage migration | Policy-gated with checkpointed auto-safe path | `AMEM_STORAGE_MIGRATION_POLICY=auto-safe|strict|off` |\n| Storage budget policy | 20-year projection + auto-rollup when budget pressure appears | `AMEM_STORAGE_BUDGET_MODE=auto-rollup|warn|off`, `AMEM_STORAGE_BUDGET_BYTES`, `AMEM_STORAGE_BUDGET_HORIZON_YEARS`, `AMEM_STORAGE_BUDGET_TARGET_FRACTION` |\n| Prompt + feedback auto-capture | Captures MCP prompt/tool context into `.amem` with privacy controls | `AMEM_AUTO_CAPTURE_MODE=safe|full|off`, `AMEM_AUTO_CAPTURE_REDACT=true|false`, `AMEM_AUTO_CAPTURE_MAX_CHARS` |\n| Maintenance throttling | SLA-aware under sustained mutation load | `AMEM_SLA_MAX_MUTATIONS_PER_MIN` |\n| Health ledger | Periodic operational snapshots (default: `~/.agentra/health-ledger`) | `AMEM_HEALTH_LEDGER_DIR`, `AGENTRA_HEALTH_LEDGER_DIR`, `AMEM_HEALTH_LEDGER_EMIT_SECS` |\n\n---\n\n\u003ca name=\"mcp-server\"\u003e\u003c/a\u003e\n\n## MCP Server\n\n**Any MCP-compatible client gets instant access to persistent graph memory.** The `agentic-memory-mcp` crate exposes the full AgenticMemory engine over the [Model Context Protocol](https://modelcontextprotocol.io) (JSON-RPC 2.0 over stdio).\n\n```bash\ncargo install agentic-memory-mcp\n```\n\n### Configure Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentic-memory\": {\n      \"command\": \"agentic-memory-mcp\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n\u003e Zero-config: defaults to `~/.brain.amem`. Override with `\"args\": [\"--memory\", \"/path/to/brain.amem\", \"serve\"]`.\n\n**Memory modes** — control how aggressively Claude saves:\n\n| Mode | Behavior | Config |\n|:---|:---|:---|\n| **smart** (default) | Auto-saves facts, decisions, preferences | `[\"serve\"]` |\n| **minimal** | Only saves when you say \"remember\" | `[\"serve\", \"--mode\", \"minimal\"]` |\n| **full** | Saves everything, creates session summaries | `[\"serve\", \"--mode\", \"full\"]` |\n\n### Configure VS Code / Cursor\n\nAdd to `.vscode/settings.json`:\n\n```json\n{\n  \"mcp.servers\": {\n    \"agentic-memory\": {\n      \"command\": \"agentic-memory-mcp\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### What the LLM gets\n\n| Category | Count | Examples |\n|:---|---:|:---|\n| **Tools** | 12 | `memory_add`, `memory_query`, `memory_traverse`, `memory_correct`, `memory_resolve`, `memory_similar`, `memory_causal`, `session_start` ... |\n| **Resources** | 6 | `amem://node/{id}`, `amem://session/{id}`, `amem://graph/stats` ... |\n| **Prompts** | 4 | `remember`, `reflect`, `correct`, `summarize` |\n\nOnce connected, the LLM can store facts, traverse reasoning chains, correct beliefs, run causal impact analysis, and maintain session continuity -- all backed by the same `.amem` binary graph. [Full MCP docs -\u003e](crates/agentic-memory-mcp/README.md)\n\n---\n\n\u003ca name=\"quickstart\"\u003e\u003c/a\u003e\n\n## Quickstart\n\n### Full agent with memory -- 5 lines\n\n```python\nfrom agentic_memory import Brain, MemoryAgent\nfrom agentic_memory.integrations import AnthropicProvider\n\nbrain = Brain(\"my_agent.amem\")\nagent = MemoryAgent(brain=brain, provider=AnthropicProvider(), verbose=True)\n\n# Session 1\nagent.chat(\"My name is Marcus. I'm building a Rust compiler.\", session=1)\n\n# Session 2 -- the agent remembers\nresponse = agent.chat(\"What am I working on?\", session=2)\n# -\u003e \"You're building a Rust compiler, Marcus.\"\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/agent-demo.svg\" alt=\"MemoryAgent verbose output showing recall, thinking, and save\" width=\"750\"\u003e\n\u003c/p\u003e\n\n### Use the brain directly -- no LLM needed\n\n```python\nfrom agentic_memory import Brain\n\nbrain = Brain(\"my_agent.amem\")\n\n# Build knowledge\nfact = brain.add_fact(\"User lives in Toronto\", session=1, confidence=0.95)\ndec = brain.add_decision(\"Chose PostgreSQL -- team knows it well\", session=2)\nbrain.link(dec, fact, \"caused_by\")\n\n# Correct without erasing\nbrain.add_correction(\"User moved to Vancouver\", session=5, supersedes=fact)\n\n# Navigate\nbrain.traverse(dec, edges=[\"caused_by\"])     # Why this decision?\nbrain.resolve(fact)                          # -\u003e \"User moved to Vancouver\"\nbrain.impact(fact)                           # What depends on this?\n\n# Search (v0.2)\nbrain.search(\"PostgreSQL\")                   # Hybrid BM25 + vector\nbrain.search_text(\"Vancouver\")              # Exact term match (1.58 ms @ 100K)\n\n# Reason about your own reasoning (v0.2)\nbrain.revise(\"Team switched to MySQL\")       # What breaks?\nbrain.gaps()                                 # Where am I guessing?\nbrain.centrality()                           # What are my core beliefs?\nbrain.drift(\"database choice\")              # How has this evolved?\nbrain.analogy(node_id=42)                   # Similar past patterns\nbrain.consolidate(dry_run=True)             # Dedup, find contradictions\nbrain.shortest_path(src=42, dst=99)         # How are these connected?\n```\n\n### Same brain, different LLMs\n\n```python\nfrom agentic_memory import Brain, MemoryAgent\nfrom agentic_memory.integrations import AnthropicProvider, OpenAIProvider\n\nbrain = Brain(\"shared_brain.amem\")\n\n# Monday: Claude learns\nMemoryAgent(brain, AnthropicProvider()).chat(\n    \"I decided to use Kubernetes for deployment\", session=10\n)\n\n# Tuesday: GPT remembers everything Claude learned\nresponse = MemoryAgent(brain, OpenAIProvider()).chat(\n    \"What's our deployment strategy?\", session=11\n)\n# -\u003e \"You decided to use Kubernetes for deployment.\"\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/cross-provider.svg\" alt=\"Cross-provider portability\" width=\"750\"\u003e\n\u003c/p\u003e\n\n---\n\n## How It Works\n\nAgenticMemory stores knowledge as a **typed cognitive event graph** in a custom binary format.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/brain-graph.svg\" alt=\"Cognitive event graph with typed nodes, causal edges, and belief revision\" width=\"800\"\u003e\n\u003c/p\u003e\n\n**Nodes** are cognitive events -- six types:\n\n| Type | What | Example |\n|:---|:---|:---|\n| **Fact** | Something learned | \"User is a senior Rust developer\" |\n| **Decision** | Choice + reasoning | \"Chose PostgreSQL -- team has 5 years experience\" |\n| **Inference** | Synthesized knowledge | \"User is likely a systems architect\" |\n| **Correction** | Updated information | \"User now works at DataFlow (was TechCorp)\" |\n| **Skill** | Learned preference | \"Use analogies when explaining concurrency\" |\n| **Episode** | Session summary | \"Discussed migration strategy, chose blue-green\" |\n\n**Edges** are relationships -- seven types: `caused_by` . `supports` . `contradicts` . `supersedes` . `related_to` . `part_of` . `temporal_next`\n\n**Queries** -- sixteen types spanning retrieval, graph algorithms, and five novel cognitive operations that [don't exist in any other system](#novel-queries).\n\n**The binary `.amem` file** uses fixed-size records (O(1) access), LZ4-compressed content, memory-mapped I/O, inline feature vectors, and a BM25 inverted index. No parsing overhead. No external services. Instant access.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFile format details\u003c/strong\u003e\u003c/summary\u003e\n\n```\n+-------------------------------------+\n|  HEADER           64 bytes          |  Magic . version . dimension . counts . feature flags\n+-------------------------------------+\n|  NODE TABLE       fixed-size rows   |  type . session . confidence . timestamp . offset\n+-------------------------------------+\n|  EDGE TABLE       fixed-size rows   |  source . target . type . weight\n+-------------------------------------+\n|  CONTENT BLOCK    LZ4 compressed    |  UTF-8 text for each node\n+-------------------------------------+\n|  FEATURE VECTORS  128-dim f32       |  Embedding vectors for similarity\n+-------------------------------------+\n|  INDEXES                            |  type . session . temporal . cluster . BM25 term . doc lengths\n+-------------------------------------+\n```\n\nv0.2 adds BM25 term index (tag 0x05) and document lengths (tag 0x06) to the index block, plus feature flags in the header. Fully backward compatible -- v0.1 readers skip unknown tags. v0.2 readers handle files with or without BM25 indexes via automatic slow-path fallback (77x slower but correct).\n\n[Full format specification -\u003e](docs/file-format.md)\n\u003c/details\u003e\n\n---\n\n## Validation\n\nThis isn't a prototype. It's tested beyond what most production systems require.\n\n| Suite | Tests | |\n|:---|---:|:---|\n| Rust core engine | **179** | 13 criterion benchmarks |\n| MCP server + bridge | **135** | Protocol, tools, resources, prompts, sessions, edge cases, integration bridge |\n| Python SDK | **104** | 8 test modules, query expansion coverage |\n| Terminal agent | **97** | 6 validation protocols |\n| Cross-provider | **21** | Claude \u003c-\u003e GPT \u003c-\u003e Ollama |\n| Auto-installer | **39** | Sandboxed config tests |\n| **Total** | **575** | All passing |\n\nCross-provider tests prove: facts, decisions, corrections, skills, and reasoning chains transfer perfectly between Claude, GPT-4o, and Ollama (including models as small as 1B parameters). Cross-version tests prove: v0.1 files load in v0.2, v0.2 files load in v0.1 (unknown indexes gracefully skipped).\n\n**Three research papers:**\n- [Paper I: AgenticMemory format + v0.1 (7 pages, 7 figures, 6 tables)](paper/paper-i-format/agenticmemory-paper.pdf)\n- [Paper II: Query Expansion -- 9 new query types (10 pages, 9 figures, 6 tables, real Criterion data)](paper/paper-ii-query-expansion/agenticmemory-query-expansion.pdf)\n- [Paper III: MCP Server -- universal LLM access via Model Context Protocol](paper/paper-iii-mcp-server/agentic-memory-mcp-paper.pdf)\n\n---\n\n## Repository Structure\n\nThis is a Cargo workspace monorepo containing the core library, MCP server, and integration bridge tests.\n\n```\nagentic-memory/\n├── Cargo.toml                    # Workspace root\n├── crates/\n│   ├── agentic-memory/           # Core library (crates.io: agentic-memory v0.2.0)\n│   └── agentic-memory-mcp/       # MCP server (crates.io: agentic-memory-mcp v0.1.0)\n├── tests/bridge/                 # Integration tests (core ↔ MCP)\n├── python/                       # Python SDK (PyPI: agentic-brain)\n├── agent/                        # Terminal test agent\n├── installer/                    # Auto-installer (PyPI: amem-installer)\n├── examples/                     # Python + Rust usage examples\n├── paper/                        # Research papers (I, II, III)\n└── docs/                         # Quickstart, API ref, concepts, benchmarks\n```\n\n### Running Tests\n\n```bash\n# All workspace tests (unit + integration + bridge)\ncargo test --workspace\n\n# Bridge integration tests only\ncargo test -p agentic-memory-bridge-tests\n\n# Stress tests\ncargo test -p agentic-memory-bridge-tests --test bridge_stress\n```\n\n### MCP Server Quick Start\n\n```bash\ncargo install agentic-memory-mcp\n```\n\nConfigure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"agentic-memory\": {\n      \"command\": \"agentic-memory-mcp\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n---\n\n## Roadmap: v0.2.0 — Remote Server Support\n\nThe next release is planned to add HTTP/SSE transport for remote deployments. Track progress in [#1](https://github.com/agentralabs/agentic-memory/issues/1).\n\n| Feature | Status |\n|:---|:---|\n| `--token` bearer auth | Planned |\n| `--multi-tenant` per-user brain files | Planned |\n| `/health` endpoint | Planned |\n| `--tls-cert` / `--tls-key` native HTTPS | Planned |\n| `delete` / `export` / `compact` CLI commands | Planned |\n| Docker image + compose | Planned |\n| Remote deployment docs | Planned |\n\nPlanned CLI shape (not available in current release):\n\n```text\nagentic-memory-mcp serve-http --memory /data/brain.amem --port 8080 --token \"\u003ctoken\u003e\"\nagentic-memory-mcp serve-http --multi-tenant --data-dir /data/users --port 8080 --token \"\u003ctoken\u003e\"\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). The fastest ways to help:\n\n1. **Try it** and [file issues](https://github.com/agentralabs/agentic-memory/issues)\n2. **Add an LLM provider** -- write an integration for a new backend\n3. **Write an example** -- show a real use case\n4. **Improve docs** -- every clarification helps someone\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt by \u003ca href=\"https://github.com/agentralabs\"\u003e\u003cstrong\u003eAgentra Labs\u003c/strong\u003e\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","funding_links":["https://github.com/sponsors/xeo-labs"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentralabs%2Fagentic-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentralabs%2Fagentic-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentralabs%2Fagentic-memory/lists"}