mindgardener 1.0.0
Local-first long-term memory for autonomous agents. Wiki knowledge graph, surprise scoring, identity-level consolidation.
License: MIT
Requires Python: >=3.10
Keywords: agents, ai, knowledge-graph, llm, memory

# 🌱 MindGardener

**Your agents forget everything. This fixes it.**

```bash
pip install mindgardener
garden init
```

That's it. Your agent now has persistent memory. No database. No server. No Docker. Just files.

---

## The Problem

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** |

## The Fix

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`.

---

## What You Get

After a month, your agent has:
- **30–80 entity files** — one per person, company, project (`memory/entities/Kadoa.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 4000` loads exactly what fits
- **Identity model** — tracks *who your agent thinks you are* and updates when beliefs shift

---

## Quick Start

```bash
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 budget
```

For fully local (no API key): `garden init --provider ollama`

### The Nightly Sleep Cycle

Run this on a cron (or manually). It's your agent's equivalent of sleep:

```bash
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 days
```

### Retrieval (no LLM needed)

```bash
garden recall "Kadoa"                     # 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 model
```

---

## How Memory Actually Works

### 1. Entity Extraction

`garden extract` reads a daily log and creates one `.md` file per entity:

```markdown
# Kadoa
**Type:** company

## Facts
- AI web scraping startup (YC W24)

## Timeline
### [[2026-02-16]]
- [[Marcus]] received reply from [[Adrian Krebs]] after [[HN]] outreach
- [[Revenue Hunter]] sent cold email to adrian@kadoa.com
```

Each `[[wikilink]]` is an edge in the knowledge graph. The graph emerges from the text — no schema, no migration.

### 2. Surprise Scoring

Not all memories are equal. MindGardener uses **prediction error** to score importance:

1. Read the agent's current world model (`MEMORY.md`)
2. Predict what should have happened today
3. Compare prediction against what actually happened
4. 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.

### 3. Context Assembly (v2)

`garden context` solves the "load everything" problem. Instead of dumping all memory into context, it:

1. Scores all entities against your query (fuzzy matching, Levenshtein, initials)
2. Follows `[[wikilinks]]` — 1-hop graph traversal to find related entities
3. Includes matching graph triplets
4. Adds relevant lines from recent daily logs
5. Includes MEMORY.md excerpts
6. **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:

```json
{
  "query": "Kadoa",
  "token_budget": 4000,
  "tokens_used": 1847,
  "utilization": 0.46,
  "loaded_count": 7,
  "skipped_count": 2,
  "skipped_reasons": ["token_budget_exceeded"]
}
```

---

## All 13 Commands

| 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 |

Only 3 commands call an LLM. The other 10 are pure file operations.

---

## LLM Providers

MindGardener works with any LLM. Configure in `garden.yaml`:

```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.

---

## Configuration

```yaml
# 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
```

---

## Architecture

```
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Daily Logs  │────▶│   Extractor   │────▶│  Entity Pages   │
│  (episodic)  │     │  (LLM call)   │     │  (semantic wiki) │
└─────────────┘     └──────────────┘     └─────────────────┘
                           │                       │
                           ▼                       ▼
                    ┌──────────────┐     ┌─────────────────┐
                    │  Graph Store  │     │ Surprise Scorer  │
                    │  (triplets)   │     │ (prediction err) │
                    └──────────────┘     └─────────────────┘
                                                   │
                                                   ▼
                                          ┌─────────────────┐
                                          │  Consolidator    │
                                          │ (→ MEMORY.md)    │
                                          └─────────────────┘
                                                   │
                                                   ▼
                                          ┌─────────────────┐
                                          │ Context Assembly  │
                                          │ (budget-aware)    │
                                          └─────────────────┘
```

---

## Comparison

| | **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 |

---

## Dependencies

- Python 3.10+
- PyYAML
- An LLM provider

That's it. No numpy. No torch. No vector database. No Docker.

Install size: <500KB.

---

## Testing

```bash
$ python -m pytest tests/ -q
120 passed in 2.34s
```

120 tests. All run in <3 seconds. No network calls (all mocked).

---

## File Structure

```
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/
        ├── Marcus.md                # Person
        ├── Kadoa.md                 # Company
        ├── MindGardener.md          # Project
        └── Adrian-Krebs.md          # Person
```

Everything is a text file. Everything is `grep`-able. Everything is `git`-able.

---

## Multi-Agent Support

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.

---

## Research Background

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.

---

## Roadmap

- [x] Entity extraction from markdown logs
- [x] Wiki-style pages with `[[wikilinks]]`
- [x] Knowledge graph (JSONL triplets)
- [x] Surprise scoring (prediction error)
- [x] Token-budget-aware context assembly
- [x] Context manifests (audit trail)
- [x] Multi-provider LLM support (5 providers)
- [x] Multi-agent shared brain
- [x] 120 tests
- [ ] Concurrency safety (file locks)
- [ ] Optional embedding plugin
- [ ] Incremental indexing
- [ ] Background daemon mode
- [ ] Context evaluator (fact-checking loop)
- [ ] pip package on PyPI

---

## License

MIT

## Credits

Built by the [Swarm](https://github.com/widingmarcus-cyber/discord-agent-swarm) — a team of autonomous AI agents coordinating via Discord.