llms.txt
# YourMemory
> Persistent memory for AI agents — built on the science of how humans remember.
YourMemory is an open-source, local-first memory layer for AI agents (Claude, Cursor, Cline, Windsurf, and any MCP-compatible client). It gives AI assistants persistent memory across sessions using the Ebbinghaus forgetting curve, hybrid BM25 + vector retrieval, and an entity-based knowledge graph. One `pip install`, zero infrastructure required.
## Key Features
- **Ebbinghaus decay** — memories fade exponentially over time; importance and recall frequency slow that decay. Weak memories are pruned automatically every 24 hours.
- **Hybrid retrieval** — BM25 keyword scoring + cosine vector similarity, combined as `0.4 × bm25 + 0.6 × cosine`.
- **Entity graph** — spaCy NER links memories that share named entities, enabling multi-hop reasoning across facts that have low embedding similarity.
- **Subject-aware deduplication** — incoming memories are merged, reinforced, or replaced based on semantic similarity and contradiction detection. Never merges facts about different entities.
- **Spatial memory** — memories tagged with file/directory paths get a retrieval boost when the agent is working in that context.
- **`yourmemory ask`** — CLI command that answers factual questions from memory using a local Ollama model. Zero cloud API calls, zero tokens.
- **Memory dashboard** — built-in browser UI at `localhost:3033/ui` to browse, filter, and sort memories by strength, category, and agent.
- **Graph visualization** — interactive Cytoscape.js graph at `localhost:3033/graph` showing how memories are connected.
- **Multi-agent support** — isolated private memories per agent with controlled access to shared context.
## Benchmark Results
| Benchmark | Metric | Score |
|-----------|--------|-------|
| LongMemEval-S (500 questions) | Recall-all@5 | 84.8% |
| LoCoMo-10 (1,534 QA pairs) | Recall@5 | 59% vs Zep Cloud 28% |
| HotpotQA distractor (200 multi-hop questions) | BOTH_FOUND@5 | 71.5% |
HotpotQA tests whether a memory system can connect a chain of facts — not just retrieve similar ones. Entity graph edges add +12 pp over similarity-only retrieval on bridge-type questions.
## Tech Stack
- **Database:** DuckDB (default, zero setup) or PostgreSQL + pgvector
- **Graph:** NetworkX (default) or Neo4j
- **Embeddings:** `multi-qa-mpnet-base-dot-v1` via sentence-transformers (local, 768 dims)
- **NLP:** spaCy (local, for deduplication and entity extraction)
- **Protocol:** MCP (Model Context Protocol) stdio server
- **API:** FastAPI HTTP server on port 3033
## MCP Tools
- `recall_memory(query, user_id, current_path?)` — hybrid retrieval with graph expansion and spatial boost
- `store_memory(content, importance, category?, context_paths?, visibility?)` — embed, deduplicate, store, index
- `update_memory(memory_id, new_content, importance)` — re-embed, replace, log to audit trail
## Memory Categories and Decay Rates
| Category | Half-life | Use case |
|----------|-----------|----------|
| strategy | ~38 days | Successful patterns, approaches that worked |
| fact | ~24 days | Preferences, identity, project decisions |
| assumption | ~19 days | Inferred, uncertain context |
| failure | ~11 days | Errors, environment-specific issues |
## Links
- [GitHub](https://github.com/sachitrafa/YourMemory)
- [PyPI](https://pypi.org/project/yourmemory/)
- [Benchmarks](https://github.com/sachitrafa/YourMemory/blob/main/BENCHMARKS.md)
- [Homepage](https://yourmemoryai.xyz)
## Install
```bash
pip install yourmemory
yourmemory-path # prints config block to paste into your AI client
```
## Author
Sachit Misra — mishrasachit1@gmail.com
License: CC-BY-NC-4.0 (free for personal, education, research, open-source; commercial use requires agreement)
