{
  "markdown": "# NeuralMemory\n\n[![GitHub stars](https://img.shields.io/github/stars/nhadaututtheky/neural-memory?style=social)](https://github.com/nhadaututtheky/neural-memory/stargazers)\n[![PyPI](https://img.shields.io/pypi/v/neural-memory.svg)](https://pypi.org/project/neural-memory/)\n[![Downloads](https://img.shields.io/pypi/dm/neural-memory)](https://pypi.org/project/neural-memory/)\n[![CI](https://github.com/nhadaututtheky/neural-memory/workflows/CI/badge.svg)](https://github.com/nhadaututtheky/neural-memory/actions)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![VS Code](https://img.shields.io/visual-studio-marketplace/v/neuralmem.neuralmemory?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=neuralmem.neuralmemory)\n[![OpenClaw Plugin](https://img.shields.io/npm/v/neuralmemory?label=OpenClaw)](https://www.npmjs.com/package/neuralmemory)\n\n**Your AI agent forgets everything between sessions. Neural Memory gives it a brain.**\n\n<p align=\"center\">\n  <strong><a href=\"https://neuralmemory.theio.vn\">Website</a></strong> ·\n  <a href=\"https://neuralmemory.theio.vn/guides/quickstart-guide/\">Quickstart</a> ·\n  <a href=\"https://neuralmemory.theio.vn/api/mcp-tools/\">MCP Tools</a> ·\n  <a href=\"https://neuralmemory.theio.vn/landing/pro-landing.html\">Pro</a> ·\n  <a href=\"https://neuralmemory.theio.vn/changelog/\">Changelog</a>\n</p>\n\n<p align=\"center\">\n  <img src=\"docs/assets/images/hero-brain.svg\" alt=\"Neural Memory — spreading activation\" width=\"720\"/>\n</p>\n\nMemories are stored as interconnected neurons and recalled through spreading activation — the same way the human brain works. No vector database. No API calls. No monthly embedding bill.\n\n```bash\npip install neural-memory\n```\n\nRestart your AI tool. Your agent now remembers — no `init` needed, the MCP server auto-initializes on first use.\n\n**Already installed?** `nmem update` upgrades in place and detects whether you installed via pip or from source. `nmem update --check` only reports what is available.\n\n> The CLI is `nmem` (or the longer `neural-memory`). There is no `nm` binary.\n\n---\n\n## 3 Tools. That's It.\n\n63 MCP tools are available, but you only need three:\n\n| Tool | What it does |\n|------|-------------|\n| `nmem_remember` | Store a memory — auto-detects type, tags, and connections |\n| `nmem_recall` | Recall through spreading activation — related memories surface naturally |\n| `nmem_health` | Brain health score (A–F) with actionable fix suggestions |\n\nEverything else — sessions, context loading, habit tracking, maintenance — works transparently in the background.\n\n> [All 63 MCP tools →](https://neuralmemory.theio.vn/api/mcp-tools/)\n\n---\n\n## What Makes This Different\n\nMost memory tools are search engines. Neural Memory is a **graph that thinks**.\n\nWhen you ask \"Why did Tuesday's outage happen?\", a vector database returns the most similar sentence. Neural Memory traces the chain:\n\n```\noutage ← CAUSED_BY ← JWT expiry ← SUGGESTED_BY ← Alice's review\n```\n\n**Relationships are explicit** — `CAUSED_BY`, `LEADS_TO`, `RESOLVED_BY`, `CONTRADICTS` — so your agent doesn't just find memories, it *reasons* through them.\n\n| | Search-based (RAG) | Neural Memory |\n|--|---------------------|---------------|\n| Retrieval | Similarity score | Graph traversal |\n| Relationships | None | 24 explicit types |\n| LLM required | Yes (embedding) | No — fully offline |\n| Multi-hop reasoning | Multiple queries | One traversal |\n| Memory lifecycle | Static | Decay, reinforcement, consolidation |\n| Cost per 1K queries | ~$0.02 | **$0.00** |\n\n---\n\n## Cloud Sync — Your Data, Your Infrastructure\n\nSync your brain across every machine. Unlike other memory tools, **we never store your data**.\n\n```\nLaptop ←→ Your Cloudflare Worker ←→ Desktop\n                  ↕\n              Your Phone\n```\n\nYou deploy the sync hub to **your own Cloudflare account** (free tier). Your D1 database, your encryption key, your data. We provide the code — you own the infrastructure.\n\n```bash\nnmem sync              # push/pull changes\nnmem sync --auto       # auto-sync after every remember/recall\n```\n\nSync uses **Merkle delta** — only diffs travel, not the full brain. Fast, efficient, private.\n\n> [Cloud Sync setup guide →](https://neuralmemory.theio.vn/guides/cloud-sync/)\n\n---\n\n## Features\n\n#### Memory & Recall\n- **14 memory types** — fact, decision, error, insight, preference, workflow, instruction, and more\n- **Spreading activation** — memories surface by association, not keyword match\n- **Cognitive reasoning** — hypothesize, submit evidence, make predictions, verify with Bayesian confidence\n- **Workload presets** — `nmem config preset {balanced,safe-cost,max-recall,chat-heavy}` tune the brain for SaaS, frugal mode, deep retention, or conversational agents\n- **Temporal recall** — `nmem_causal` exposes `temporal_range` and `temporal_neighborhood` actions; see the [Temporal Recall Recipes guide](https://neuralmemory.theio.vn/guides/temporal-recipes/)\n\n#### Knowledge Ingestion\n- **Train from documents** — PDF, DOCX, PPTX, HTML, JSON, XLSX, CSV ingested into permanent brain knowledge\n- **Import adapters** — migrate from ChromaDB, Mem0, Cognee, Graphiti, LlamaIndex in one command\n\n#### Lifecycle & Storage\n- **Memory consolidation** — episodic memories mature into semantic knowledge over time\n- **Compression tiers** — full → summary → essence → ghost → metadata (reclaim storage, keep meaning)\n- **Brain versioning** — snapshot, rollback, diff, transplant memories between brains\n\n#### Community\n- **Brain Store** — browse, import, and publish pre-built brains to the community marketplace\n- **3 seed brains** — Python Best Practices, Git Workflows, Docker Essentials (ready to import)\n\n#### Ecosystem\n- **Web dashboard** — 7-page React UI with graph visualization, health radar, timeline, mindmap, Brain Store\n- **VS Code extension** — memory tree, graph explorer, CodeLens, WebSocket sync ([Marketplace →](https://marketplace.visualstudio.com/items?itemName=neuralmem.neuralmemory))\n- **Safety** — Fernet encryption, sensitive content auto-detection, parameterized SQL, path validation\n- **Telegram backup** — send brain `.db` files to Telegram for offsite backup\n\n---\n\n## Quick Examples\n\n```bash\n# Store memories (type auto-detected)\nnmem remember \"Fixed auth bug with null check in login.py:42\"\nnmem remember \"We decided to use PostgreSQL\" --type decision\nnmem todo \"Review PR #123\" --priority 7\n\n# Recall\nnmem recall \"auth bug\"\nnmem recall \"database decision\" --depth 2\n\n# Brain management\nnmem brain list && nmem brain health\nnmem brain export -o backup.json\n\n# Sync across devices\nnmem sync --full\n\n# Web dashboard\nnmem serve    # http://localhost:8000/dashboard\n```\n\n```python\nimport asyncio\nfrom neural_memory import Brain\nfrom neural_memory.storage import InMemoryStorage\nfrom neural_memory.engine.encoder import MemoryEncoder\nfrom neural_memory.engine.retrieval import ReflexPipeline\n\nasync def main():\n    storage = InMemoryStorage()\n    brain = Brain.create(\"my_brain\")\n    await storage.save_brain(brain)\n    storage.set_brain(brain.id)\n\n    encoder = MemoryEncoder(storage, brain.config)\n    await encoder.encode(\"Met Alice to discuss API design\")\n    await encoder.encode(\"Decided to use FastAPI for backend\")\n\n    pipeline = ReflexPipeline(storage, brain.config)\n    result = await pipeline.query(\"What did we decide about backend?\")\n    print(result.context)  # \"Decided to use FastAPI for backend\"\n\nasyncio.run(main())\n```\n\n---\n\n## Neural Memory Pro\n\nFree Neural Memory is complete — 63 tools, unlimited memories, fully offline. **You never have to pay.**\n\nBut past 10K memories, things change. Keyword matching misses semantically related content. Consolidation slows to minutes. Storage grows unbounded. If your agent's brain is getting big, Pro makes it smart.\n\n### Free recalls by keyword. Pro recalls by meaning.\n\n```\nQuery: \"authentication improvements\"\n\nFree (FTS5):  2 results — exact matches only\nPro  (HNSW):  7 results — includes \"JWT rotation\", \"session hardening\", \"OAuth migration\"\n```\n\n### What Pro adds\n\n| | Free (SQLite) | Pro (InfinityDB) |\n|--|:---:|:---:|\n| **Recall** | Keyword match (FTS5) | Semantic similarity (HNSW) |\n| **Speed at 1M neurons** | ~500ms | **<5ms** |\n| **Scale tested** | ~50K neurons | 2M+ neurons |\n| **Compression** | Text-level trimming | 5-tier vector compression (97% savings) |\n| **Consolidation** | O(N²) brute-force | O(N×k) HNSW clustering |\n| **Storage per 1M** | ~5 GB | **~1 GB** |\n| **Cloud sync** | Manual push/pull | Merkle delta (auto, diffs only) |\n\n### Pro-exclusive features\n\n- **Cone Queries** — adjustable semantic recall. Narrow the cone for precision, widen for exploration\n- **Smart Merge** — consolidation that scales to 1M+ neurons using HNSW neighbor clustering\n- **Directional Compression** — compress along multiple semantic axes while preserving meaning\n- **5-Tier Auto Lifecycle** — memories flow from float32 → float16 → int8 → binary → metadata. Auto-promote on access\n\n### Get Pro\n\n```bash\npip install neural-memory                 # Pro features included\nnmem shared activate --key NM-PRO-XXXX-XXXX-XXXX   # activate license\nnmem shared status                                 # verify: Pro: Active\n```\n\n**[$9/mo](https://neuralmemory.theio.vn/landing/pricing/)** — 30-day money-back guarantee. All free tools keep working. Downgrade anytime, keep your data.\n\n> [Pro quickstart →](https://neuralmemory.theio.vn/guides/pro-quickstart/) · [Full comparison →](https://neuralmemory.theio.vn/landing/pro/) · [Pricing →](https://neuralmemory.theio.vn/landing/pricing/)\n\n---\n\n## Setup by Tool\n\n<details>\n<summary><b>Claude Code (Plugin)</b></summary>\n\n```bash\n/plugin marketplace add nhadaututtheky/neural-memory\n/plugin install neural-memory@neural-memory-marketplace\n```\n\n</details>\n\n<details>\n<summary><b>Cursor / Windsurf / Other MCP Clients</b></summary>\n\n```bash\npip install neural-memory\n```\n\nAdd to your editor's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"neural-memory\": { \"command\": \"nmem-mcp\" }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>OpenClaw (Skill or Plugin)</b></summary>\n\n**Skill — one click via ClawHub.** Published on every release:\n\n[clawhub.ai/skills/neural-memory](https://clawhub.ai/skills/neural-memory)\n\n**Plugin — memory slot replacement.** Use this if you want NeuralMemory to *be*\nOpenClaw's memory provider rather than a skill it calls:\n\n```bash\npip install neural-memory && npm install -g neuralmemory\n```\n\nSet memory slot in `~/.openclaw/openclaw.json`:\n```json\n{ \"plugins\": { \"slots\": { \"memory\": \"neuralmemory\" } } }\n```\n\n</details>\n\n<details>\n<summary><b>Upgrade to Pro</b></summary>\n\nAlready using Neural Memory? Just activate your key:\n\n```bash\nnmem shared activate --key NM-PRO-XXXX-XXXX-XXXX   # activate license\n```\n\nThen enable InfinityDB (semantic search engine):\n\n```toml\n# ~/.neuralmemory/config.toml\nstorage_backend = \"infinitydb\"\n```\n\nRestart your MCP server. Existing memories are auto-migrated from SQLite to InfinityDB on first startup.\n\n> [Get a license →](https://neuralmemory.theio.vn/landing/pricing/) · [Pro quickstart →](https://neuralmemory.theio.vn/guides/pro-quickstart/)\n\n</details>\n\n<details>\n<summary><b>Installation extras</b></summary>\n\n```bash\npip install neural-memory[server]              # FastAPI server + dashboard\npip install neural-memory[extract]             # PDF/DOCX/PPTX/HTML/XLSX extraction\npip install neural-memory[nlp-vi]              # Vietnamese NLP\npip install neural-memory[embeddings]          # Local embedding models\npip install neural-memory[embeddings-openai]   # OpenAI embeddings\npip install neural-memory[all]                 # Everything\n```\n\n</details>\n\n<details>\n<summary><b>Benchmarks vs alternatives</b></summary>\n\n| Metric | NeuralMemory | Mem0 | Cognee |\n|--------|:---:|:---:|:---:|\n| **Write 50 memories** | 1.2s | 148.2s (121x slower) | 290.6s (80x slower) |\n| **Read 20 queries** | 1.8s | 2.9s | 34.6s |\n| **API calls** | **0** | 70 | 149 |\n\nZero LLM calls, zero API cost. [Full benchmarks →](docs/benchmarks.md) ·\n[Cognitive Efficiency release evidence →](docs/benchmarks.md#cognitive-efficiency-release-evidence-phase-8)\n\n</details>\n\n---\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Quickstart Guide](https://neuralmemory.theio.vn/guides/quickstart-guide/) | Interactive guide with animated demos |\n| [Pro Quickstart](https://neuralmemory.theio.vn/guides/pro-quickstart/) | Get started with Pro features |\n| [CLI Reference](https://neuralmemory.theio.vn/getting-started/cli-reference/) | All 82 CLI commands |\n| [MCP Tools Reference](https://neuralmemory.theio.vn/api/mcp-tools/) | All 63 MCP tools with parameters |\n| [Cloud Sync](https://neuralmemory.theio.vn/guides/cloud-sync/) | Multi-device sync setup |\n| [Brain Health Guide](https://neuralmemory.theio.vn/guides/brain-health/) | Understanding and improving brain health |\n| [Embedding Setup](https://neuralmemory.theio.vn/guides/embedding-setup/) | Configure embedding providers |\n| [Architecture](https://neuralmemory.theio.vn/architecture/overview/) | Technical design deep-dive |\n\n## Development\n\n```bash\ngit clone https://github.com/nhadaututtheky/neural-memory\ncd neural-memory && pip install -e \".[dev]\"\nnmem doctor --dev        # Verify contributor setup\npytest tests/ -v          # 7800+ tests\nruff check src/ tests/    # Lint\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Support\n\nIf Neural Memory helps your AI agent remember, please consider giving it a star — it helps others discover the project and keeps development going.\n\n<a href=\"https://github.com/nhadaututtheky/neural-memory/stargazers\">\n  <img src=\"https://img.shields.io/github/stars/nhadaututtheky/neural-memory?style=social\" alt=\"Star on GitHub\"/>\n</a>\n\nYou can also [sponsor](https://github.com/sponsors/nhadaututtheky) the project.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 13999,
  "sha": "7b4b35e035fefb824df57b11ff84e30a90fd93ceb79ea576125b7829ce6db044",
  "repo_slug": "nhadaututtheky/neural-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nhadaututtheky_neural_memory_bbb77e9d/readme"
}