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