yggdrasil

<h1 align="center">🌳 Yggdrasil</h1>

One shared, durable memory for all your AI coding agents. Claude Code, Codex, and any MCP host remember your decisions, lessons, and project status — across sessions, tools, and projects.

<a href="#-install">Install</a> · <a href="#-how-it-works">How it works</a> · <a href="#-yggdrasil-vs-the-rest">Compare</a> · <a href="#-commands">Commands</a> · <a href="#-faq">FAQ</a>

---

Every new chat, your AI forgets. You re-explain the project, the decisions, the gotchas — every time, in every tool. Yggdrasil is a tiny always-on memory brain that any agent plugs into. Open a new session, in any project, with any AI, and it already knows what you decided, what broke, and what's still open — and it keeps learning in the background.

$ cd ~/projects/checkout-api && claude        # a brand-new session

🌳 Yggdrasil  (injected automatically at session start)
   Open follow-ups & status:
   • [project_status] payments refactor: idempotency keys added; open: e2e tests
   Durable memory for `checkout-api`:
   • [debugging_lesson] webhook 401 → signing secret rotated; update env + redeploy

> "have I solved a flaky websocket reconnect anywhere before?"

🌳 recall → found in project `realtime-dash`:
   refresh the token *before* opening the socket, then retry with capped backoff.

No "let me remind you what we did yesterday." It's just there.

Why

Without Yggdrasil you re-explain context in every new chat, lessons from one project never reach the next, switching Claude Code → Codex starts from zero, and hard-won debugging insights die with the session.

With Yggdrasil:

🧠 Persistent memory — decisions, lessons, and status survive across sessions.
🔌 Any agent, one brain — Claude Code, Codex, any MCP host share the same memory.
🌐 Cross-project recall — "this looks like what you did in project B — reuse it?"
🌱 Self-learning — a local model consolidates memory in the background (zero API tokens).
🪪 A soul — give it a name and personality; it shows up the same in every tool.
🔒 100% local & private — your memory lives on your machine. No cloud, no account.

🚀 Install

Requirements: macOS (Linux/Windows soon), Python 3.10+ — or let uv/npx fetch Python for you. Semantic search is optional and uses a local Ollama model.

uvx --from yggdrasil-memory ygg install      # recommended

<details> <summary>Prefer npm, pipx, pip, Homebrew, or source? (same engine)</summary>

| Tool | Command | | --- | --- | | npm / npx | npx yggdrasil-memory install | | pipx | pipx install yggdrasil-memory && ygg install | | pip | pip install yggdrasil-memory && ygg install | | Homebrew _(macOS)_ | brew install VonderVuflya/tap/yggdrasil && ygg install | | from source | uvx --from git+https://github.com/VonderVuflya/yggdrasil.git ygg install |

</details>

ygg install is a one-time guided setup: it detects your hardware and recommends a local model that fits (or pick none for a zero-config, lexical-only setup), generates a private auth token, installs an always-on background service, and registers the tools with Claude Code and Codex. Check it any time with ygg doctor; upgrade with ygg update.

Just want to kick the tyres without installing a service? uvx --from yggdrasil-memory ygg serve --reset --db /tmp/ygg.sqlite.

🔌 Connect your agents

ygg install already registers the tools with Claude Code and Codex. Two more ways to plug in:

🖥️ Claude Desktop (app) — install the MCP extension: grab yggdrasil-<version>.mcpb from the latest release (or packaging/mcpb/), drag it onto Settings → Extensions, and paste your token (ygg token). The desktop app now shares the same memory as your CLI agents. → setup guide
🧠 Skill (any Claude) — the yggdrasil-memory skill teaches the agent the workflow: recall before work, remember after. Upload yggdrasil-memory.zip via Settings → Skills → Create skill → Upload a skill.

MCP vs Skill: MCP connects the tools (how to reach memory); the Skill teaches when to use them. Use both for the best behavior.

🧠 How it works

Yggdrasil is memory + tools — the intelligence is your LLM. It just makes sure the right memory is in front of the right agent at the right moment.

🛎️ Always-on daemon — a tiny local service (~21 MB RAM) your agents reach over MCP tools (ygg_search, ygg_recall, ygg_remember …).
🪝 Session start — a hook auto-injects identity, project status, and open follow-ups.
📌 Ranking — frequently-recalled and pinned memories surface higher (storage & tiers below ↓).
🧹 Governance — duplicates / conflicts are surfaced for review; changes are non-destructive (archive, never delete).
📓 Obsidian — every memory is also a Markdown note you can read and edit.

🎛️ Memory tiers — zero-config by default

Out of the box, Yggdrasil runs on SQLite + FTS5 with zero dependencies — instant keyword (lexical) search, no models, no GPU, nothing to download. Already useful: recall@1 ≈ 0.77.

Want it to match by meaning and across languages? If your hardware allows, ygg install can pull optional local models via Ollama — it detects your CPU/RAM/GPU and recommends a fit (or choose none to stay zero-config). Two optional, independent tiers:

   your agents ─► ygg_search / ygg_recall / ygg_remember
                             │
                 ┌───────────▼───────────┐
                 │   SQLite  (storage)    │
                 │   ├─ FTS5 / BM25  ─────┼─►  keyword search   (always · zero-dep)
                 │   └─ embedding column ─┼─►  vector search    (optional)
                 └───────────▲───────────┘
                             │ vectors in
       optional · local:  Ollama models ── only COMPUTE vectors / run consolidation

| Tier | You add | You gain | | --- | --- | --- | | 0 · default | nothing — SQLite + FTS5 | keyword search, zero deps, instant — recall@1 ≈ 0.77 | | 1 · semantic | an embedding model via Ollama (e.g. all-minilm 45 MB · paraphrase-multilingual ~560 MB) | search by meaning + cross-lingual — recall@1 ≈ 0.94 | | 2 · self-learning | a small consolidation LLM via Ollama (e.g. qwen2.5:1.5b ~1 GB) | background dedupe/merge of memory (propose-safe) |

Ollama only computes the vectors / runs the background model — the vectors and all memories still live in the same SQLite. Tiers are independent and opt-in.

<details> <summary>Full model menu (or run <code>ygg recommend</code>)</summary>

Embeddings (semantic search):

| Model | Size | Good for | | --- | --- | --- | | all-minilm | 45 MB | English, tiny & fast | | nomic-embed-text | 274 MB | English, better quality | | paraphrase-multilingual | ~560 MB | multilingual (EN/RU + 50 langs) | | bge-m3 | 1.2 GB | multilingual, top quality (heavier) |

Background consolidation (small LLM):

| Model | Size | Good for | | --- | --- | --- | | qwen2.5:0.5b | ~400 MB | tiny, fast on CPU | | qwen2.5:1.5b | ~1 GB | best CPU default | | llama3.2:3b | ~2 GB | better quality, slower on CPU |

</details>

Everything stays 100% local — zero API tokens, no cloud. The installer recommends models that fit your hardware (or pick none to stay zero-config).

The engine itself is swappable — any service meeting the MemoryBackend contract is a drop-in (point YGG_ENGINE_URL at it); SQLite is the zero-dep default. See docs/backend-boundary.md.

🆚 Yggdrasil vs the rest

context-mode and Context7 own different layers (your live context window; fresh library docs). mem0 is the closest — it's also a memory layer, but a different kind: an SDK/platform for AI apps to remember their users. Yggdrasil is install-and-go, local-first memory of _your own_ work for the coding agents you already use — no code, no cloud, no API key.

| | Yggdrasil | mem0 | context-mode | Context7 | | --- | --- | --- | --- | --- | | Durable memory of your own work (decisions, lessons, status) | ✅ | ✅ | ⚠️ in-session | ❌ | | Drop-in for your agents, no code (install + MCP) | ✅ | ⚠️ SDK / integration | ✅ | ✅ | | Works with no LLM & no API key (zero-dep, lexical default) | ✅ | ❌ needs an LLM | ✅ | ❌ | | 100% local & private (no cloud by default) | ✅ | ⚠️ cloud default | ✅ | ☁️ hosted | | Cross-project recall ("solved this in project B") | ✅ | ⚠️ | ❌ | — | | One memory shared across tools (Claude Code · Codex · any MCP host) | ✅ | ⚠️ per-app | ✅ | ✅ | | Keeps the live context window lean | — | — | ✅ | ❌ | | Up-to-date public library docs | ❌ (use Context7) | ❌ | ❌ | ✅ |

mem0 vs Yggdrasil, in one line: mem0 is a memory SDK/platform for building apps that remember their users (you write code; it usually calls an LLM, cloud by default). Yggdrasil is drop-in, local-first memory of _your own_ work for the agents you already code with. Different job — pick by who you are.

Also pairs well with autoresearch — an autonomous experiment loop (not a memory tool); Yggdrasil gives it long-term memory of what it already tried → integration.

TL;DR: building an AI product that must remember its users at scale → mem0. You're the developer and want Claude Code / Codex to remember your decisions across projects, installed in one line, fully local → Yggdrasil.

🧰 Commands

Agents see six MCP tools: ygg_health, ygg_bootstrap, ygg_search, ygg_recall, ygg_remember, ygg_materialize. After ygg install they're auto-registered with Claude Code and Codex — just open a project and work.

<details> <summary>Full <code>ygg</code> CLI reference</summary>

Memory ops

| Command | What it does | | --- | --- | | ygg recall --query "…" | Cross-project search — "have I done this anywhere?" | | ygg search --project P --query "…" | Project-scoped search (--type, --tag, --limit, --json) | | ygg remember --project P --type debugging_lesson --content "…" | Save a durable memory (secret-guarded, deduped; --tag to label) | | ygg bootstrap --project P | Pull a project's memory before starting work | | ygg pin --id ID · ygg unpin --id ID | Pin a memory so it reliably surfaces | | ygg supersede --id ID | Archive an outdated memory a newer one replaces | | ygg materialize --id ID --project P | Export one memory to an Obsidian note |

Service & setup

| Command | What it does | | --- | --- | | ygg install · ygg setup | Guided setup → background service + MCP registration | | ygg doctor · ygg update | Diagnose the install · redeploy the latest code | | ygg status · start · stop · restart · logs | Manage the always-on daemon | | ygg hooks · unhooks | Enable/disable the SessionStart auto-bootstrap hook | | ygg recommend | Show the hardware-aware model catalog | | ygg token · uninstall | Print the auth token · remove service + registration |

Give it a personality — edit ~/.yggdrasil/identity.json:

{ "name": "Jarvis", "persona": "concise, proactive, dry wit", "user_facts": ["prefers TypeScript", "ships small PRs"] }

</details>

❓ FAQ

<details> <summary>Does it send my code or memory to the cloud?</summary>

No. The engine, the database, and the optional models all run locally. No account, no telemetry. Your memory never leaves your machine. </details>

<details> <summary>Does it automatically remember everything?</summary>

No — by design. Retrieval is automatic; writing is deliberate (the agent calls ygg_remember for durable lessons). Auto-capturing everything pollutes memory, so we don't. A background model consolidates what's already saved (propose-only by default). </details>

No. The default is pure lexical search — zero dependencies, instant. Semantic search is opt-in and uses a local model via Ollama (no API key). The installer recommends a model that fits your hardware. </details>

<details> <summary>How heavy is it, and how many tokens does it cost?</summary>

Tiny. The engine is ~21 MB RAM, ~0% idle CPU, zero dependencies (Python stdlib); disk is tens of KB per memory. Session start injects ~300 tokens of memory and each tool call returns a small snippet — all the heavy work (indexing, embeddings, consolidation) runs off-LLM on your machine. </details>

<details> <summary>How good is retrieval?</summary>

Measured by eval/ygg_eval.py (35 labelled cases, dev/holdout split), recall@1:

| Mode | recall@1 | paraphrase | crosslingual (EN→RU) | | --- | --- | --- | --- | | lexical (default) | 0.77 | 0.63 | 0.00 | | dense · all-minilm (45 MB, EN) | 0.83 | 0.88 | 0.00 | | dense · paraphrase-multilingual (~560 MB) | 0.94 | 0.88 | 0.80 |

keyword and identifier queries are 1.0 in every mode; with the multilingual model recall@3 = 1.0 (every target in the top 3). </details>

<details> <summary>Can I edit or delete memories by hand?</summary>

Yes. Memories materialize to Markdown notes in an Obsidian vault — read, edit, or remove them like any file. The engine never hard-deletes; it archives (reversible). </details>

<details> <summary>Is it production-ready?</summary>

It's an honest alpha: the happy path and the full governance loop are covered by passing gates (scripts/run_gates.sh). Not yet hardened for multi-user/production. </details>

🗺️ Roadmap

🛰️ Cross-surface sync — connect from ChatGPT / Claude on the web and mobile; one memory across CLI, browser, and phone.
🔗 Relation graph (SOLVES / SUPERSEDES / CONTRADICTS) for richer reasoning.
🐧 Linux/Windows service installers (implemented; final on-device testing).

🤝 Contributing

Issues and PRs welcome. Run scripts/run_gates.sh and python3 -m unittest discover -s tests before submitting — all gates must stay green.

📜 License

Elastic License 2.0 — see LICENSE. You may freely use, modify, self-host, and redistribute Yggdrasil. You may not sell it as a product or offer it to others as a hosted/managed service. It is source-available — not OSI open source.

Why

🚀 Install

🔌 Connect your agents

🧠 How it works

🎛️ Memory tiers — zero-config by default

🆚 Yggdrasil vs the rest

🧰 Commands

❓ FAQ

🗺️ Roadmap

🤝 Contributing

📜 License

Related MCP servers

MCP servers by category