Your agents forget everything. This fixes it.
Built for OpenClaw. Complements the built-in memory_search tool.
pip install mindgardener
garden initThat's it. Your agent now has persistent memory. No database. No server. No Docker. Just files.
Status: v1.1 — Running in production. Built for multi-agent swarms.
- 🔍 Provenance tracking — know where every fact came from
- ⚔️ Conflict detection — flags when new info contradicts old
- 🚀 Auto-injection — context ready at session start
- ⏰ Temporal decay — old facts fade unless reinforced
- 🔒 Concurrency — file locks for multi-agent safety
- 🔮 Associative recall — follow wikilinks + graph traversal
- 📊 Confidence levels — not all facts are equally reliable
- 🤝 Multi-agent sync — merge per-agent memories to shared
OpenClaw has built-in memory_search — great for finding things in your MEMORY.md. But who writes that memory? Who decides what's worth remembering?
| OpenClaw built-in | MindGardener adds |
|---|---|
| Search existing memory | Create memory from conversations |
| Manual MEMORY.md edits | Auto-extract entities → wiki pages |
| Flat text search | Knowledge graph (triplets + wikilinks) |
| — | Surprise scoring (unexpected = important) |
| — | Conflict detection (new info vs old) |
| — | Identity tracking (belief drift) |
| — | Multi-agent sync |
Together: MindGardener builds the memory. OpenClaw's memory_search finds it.
Every AI agent wakes up with amnesia. You talked for two hours about your job search, your projects, your contacts — next session, gone.
Current solutions all require infrastructure you don't want to maintain:
| Tool | You need to run |
|---|---|
| Mem0 | Neo4j + Qdrant |
| Letta (MemGPT) | Cloud server + account |
| Zep / Graphiti | Postgres |
| LangMem | Postgres |
| MindGardener | Nothing |
MindGardener reads your agent's conversation logs and builds a personal wiki — one markdown file per person, project, and event. It decides what's worth remembering using surprise scoring (prediction error), not "rate importance 1-10."
Your agent's memory is just a folder of files. grep it. git diff it. Open it in Obsidian. Back it up with cp.
After a month, your agent has:
- 30–80 entity files — one per person, company, project (
memory/entities/Acme.md) - A knowledge graph —
[[wikilinks]]+ triplets, no database needed - Curated long-term memory — only the surprising stuff survives
- Token-budget retrieval —
garden context "topic" --budget 4000loads exactly what fits - Identity model — tracks who your agent thinks you are and updates when beliefs shift
pip install mindgardener
garden init # Set up workspace
garden extract --input memory/today.md # Build entity wiki from logs
garden context "job search" --budget 4000 # Get relevant memory, within budgetFor fully local (no API key): garden init --provider ollama
If you're running OpenClaw, add MindGardener as a skill:
# In your workspace
pip install mindgardener
garden initThen add to your agent's nightly cron or BOOTSTRAP.md:
# Nightly maintenance (add to your cron)
garden extract && garden surprise && garden consolidate
# Session start (add to BOOTSTRAP.md or heartbeat)
garden inject --output RECALL-CONTEXT.mdYour agent will now:
- Build memory from daily conversation logs
- Score events by surprise (unexpected = important)
- Generate relevant context at session start
- Track conflicts when facts change
What changes from default OpenClaw?
- New
memory/entities/folder with wiki pages graph.jsonlfor knowledge tripletsRECALL-CONTEXT.mdupdated at session startgarden.yamlconfig file
Everything is markdown files. No database. Works offline.
Run this on a cron (or manually). It's your agent's equivalent of sleep:
garden extract # Read today's logs → create/update entity wiki pages
garden surprise # Score events by prediction error (what was unexpected?)
garden consolidate # Promote high-surprise events to MEMORY.md
garden beliefs --drift --apply # Update identity model if beliefs shifted
garden prune --days 30 # Archive entities inactive >30 daysgarden recall "Acme" # Search entities + graph
garden context "job search" --budget 4000 # Token-budget assembly
garden evaluate --text "Agent said X" # Fact-check against knowledge graph
garden beliefs # View identity modelgarden extract reads a daily log and creates one .md file per entity:
# Acme
**Type:** company
## Facts
- AI web scraping startup (YC W24)
## Timeline
### [[2026-02-16]]
- [[Alex]] received reply from [[Jane Smith]] after [[HN]] outreach
- [[Revenue Hunter]] sent cold email to contact@acme.comEach [[wikilink]] is an edge in the knowledge graph. The graph emerges from the text — no schema, no migration.
Not all memories are equal. MindGardener uses prediction error to score importance:
- Read the agent's current world model (
MEMORY.md) - Predict what should have happened today
- Compare prediction against what actually happened
- Score the delta: high surprise → important, low surprise → routine
This is how biological memory works — you remember the unexpected, not the routine. Ported from SOAR's impasse-driven chunking (Laird, 2012) to LLM agents.
garden context solves the "load everything" problem. Instead of dumping all memory into context, it:
- Scores all entities against your query (fuzzy matching, Levenshtein, initials)
- Follows
[[wikilinks]]— 1-hop graph traversal to find related entities - Includes matching graph triplets
- Adds relevant lines from recent daily logs
- Includes MEMORY.md excerpts
- All within a token budget — 4000 tokens? Only the most relevant. 500? Even more selective.
Every assembly is logged with a manifest — you can audit exactly what your agent knew (or didn't know) at any point:
{
"query": "Acme",
"token_budget": 4000,
"tokens_used": 1847,
"utilization": 0.46,
"loaded_count": 7,
"skipped_count": 2,
"skipped_reasons": ["token_budget_exceeded"]
}| Command | What it does | LLM? | Cost |
|---|---|---|---|
garden init |
Set up workspace | No | Free |
garden extract |
Daily log → entity wiki + graph | Yes | ~$0.001 |
garden surprise |
Score events by prediction error | Yes | ~$0.002 |
garden consolidate |
Promote high-surprise → MEMORY.md | Yes | ~$0.001 |
garden recall "q" |
Search entities + graph | No | Free |
garden context "q" |
Token-budget context assembly | No | Free |
garden entities |
List all known entities | No | Free |
garden prune |
Archive inactive entities | No | Free |
garden merge "a" "b" |
Merge duplicate entities | No | Free |
garden fix type "X" "t" |
Fix entity type mistakes | No | Free |
garden reindex |
Rebuild graph from entity files | No | Free |
garden viz |
Mermaid graph visualization | No | Free |
garden stats |
Quick overview | No | Free |
| v1.1 Commands | |||
garden add "fact" |
Add fact with provenance | No | Free |
garden conflicts |
List/manage detected conflicts | No | Free |
garden inject |
Generate context for injection | No | Free |
garden decay |
Show/prune decayed facts | No | Free |
garden sync |
Sync multi-agent memories | No | Free |
Only 3 commands call an LLM. Everything else is pure file operations.
MindGardener is local-first. Only 3 commands need an LLM (extract, surprise, consolidate). Everything else is pure file operations.
For fully local operation, use Ollama. Configure in garden.yaml:
extraction:
provider: google # Google Gemini (free tier: 1500 req/day)
model: gemini-2.0-flash| Provider | Config | Cost |
|---|---|---|
| Google Gemini | provider: google |
Free tier available |
| OpenAI | provider: openai |
From $0.15/1M tokens |
| Anthropic | provider: anthropic |
From $0.25/1M tokens |
| Ollama (local) | provider: ollama |
Free |
| Any OpenAI-compatible | provider: compatible + base_url |
Varies |
Daily cost running full nightly cycle: ~$0.004/day with Gemini Flash. ~$0.12/month. $0 with Ollama.
# garden.yaml
workspace: /path/to/workspace
memory_dir: memory/
entities_dir: memory/entities/
graph_file: memory/graph.jsonl
long_term_memory: MEMORY.md
extraction:
provider: google
model: gemini-2.0-flash
consolidation:
surprise_threshold: 0.5 # Min score to promote
decay_days: 30 # Archive after N days inactive┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Daily Logs │────▶│ Extractor │────▶│ Entity Pages │
│ (episodic) │ │ (LLM call) │ │ (semantic wiki) │
└─────────────┘ └──────────────┘ └─────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌─────────────────┐
│ Graph Store │ │ Surprise Scorer │
│ (triplets) │ │ (prediction err) │
└──────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Consolidator │
│ (→ MEMORY.md) │
└─────────────────┘
│
▼
┌─────────────────┐
│ Context Assembly │
│ (budget-aware) │
└─────────────────┘
| MindGardener | Mem0 | Letta | Zep/Graphiti | Cognee | |
|---|---|---|---|---|---|
| Infrastructure | None | Neo4j + Qdrant | Cloud server | Postgres | Heavy |
| Storage format | Markdown | Opaque | Opaque | Opaque | Opaque |
| Human-readable | Yes | No | No | No | No |
| Knowledge graph | Wikilinks + JSONL | Neo4j | No | Graph DB | Graph |
| Surprise scoring | Yes | No | No | No | No |
| Token-budget retrieval | Yes | No | No | No | No |
| Context manifests | Yes | No | No | No | No |
| Manual editing | Any editor | No | /remember | No | No |
| Browse in Obsidian | Yes | No | No | No | No |
| Offline capable | Yes (Ollama) | No | No | No | No |
| Framework lock-in | None | Mem0 SDK | Letta SDK | Zep SDK | Cognee SDK |
| Install | pip install |
Docker + DBs | Cloud signup | Docker + DB | pip + deps |
- Python 3.10+
- PyYAML
- An LLM provider
That's it. No numpy. No torch. No vector database. No Docker.
Install size: <500KB.
$ python -m pytest tests/ -q
120 passed in 2.34s172 tests. All run in <3 seconds. No network calls (all mocked).
your-workspace/
├── garden.yaml # Config
├── MEMORY.md # Long-term curated memory
└── memory/
├── 2026-02-17.md # Daily log (episodic)
├── 2026-02-16.md
├── graph.jsonl # Knowledge graph triplets
├── surprise-scores.jsonl # What was unexpected
├── context-manifests.jsonl # Audit trail
└── entities/
├── Alex.md # Person
├── Acme.md # Company
├── MindGardener.md # Project
└── Jane-Smith.md # Person
Everything is a text file. Everything is grep-able. Everything is git-able.
Multiple agents can share the same entity directory. Each contributes observations; all benefit from combined knowledge. Use symlinks or shared directories — no coordination server needed.
MindGardener draws from cognitive science research on memory:
- Tulving (1972) — Episodic vs semantic memory distinction
- SOAR (Laird, 2012) — Impasse-driven chunking for procedural learning
- Generative Agents (Park et al., 2023) — Reflection-based agent memory
- CoALA (Sumers et al., 2023) — Formal taxonomy of agent memory architectures
- MemGPT (Packer et al., 2023) — OS-inspired hierarchical memory management
- Everything is Context (Xu et al., 2025) — Filesystem abstraction for context engineering
Novel contribution: Surprise-based consolidation using prediction error, and token-budget-aware context assembly with audit manifests.
MIT
Built by a multi-agent swarm coordinating via Discord.
New features inspired by biological memory models:
# Immediate tagging, deferred processing
garden inbox --add "Got offer from Hema!" --importance high --source interview
garden inbox --add "Fixed PR typo" --importance low
# Process inbox during nightly cycle
garden inbox --process
# View inbox
garden inbox --listEvery garden recall query strengthens the accessed entities, mimicking the "retrieval practice effect" in human memory.
# Show core entities (highest importance)
garden core --top 10
# Find prune candidates (low importance, never accessed)
garden core --prune-candidates --threshold 0.1 --min-age 30Importance formula:
importance = access_count × 0.5 + recency × 0.3 + initial_tag × 0.2
Grace period: New entities (< 7 days) get boosted scores before decay kicks in.
Create memory/FOCUS.md with current priorities:
## 🔴 Active (check first)
- **Hema** (Mar 10) — Take-home submitted, waiting for offer
## 🟡 Background (don't forget)
- **MindGardener v1.2** — inbox, retrieval strengthening
## ⚪ Parked (not now)
- Trading bot (deleted)All agents read this at session boot to stay aligned.