Yggdrasil

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

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

🌳 Yggdrasil  (injected automatically at session start)
   • [project_status] payments refactor: idempotency keys added; open: e2e tests
   • [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.

🚀 Install

Two commands, inside Claude Code (the plugin launches via uv):

/plugin marketplace add VonderVuflya/Yggdrasil
/plugin install yggdrasil

The engine lazy-starts on first use and generates its own local token — no API key, no cloud, nothing to configure. Codex and Cursor use the same flow.

ygg install is a one-time guided setup: it installs an always-on background service, registers the MCP tools with Claude Code and Codex, and — if your hardware allows — recommends optional local models (or pick none to stay zero-config).

There is also a yggdrasil-memory skill for any Claude surface: MCP connects the tools, the skill teaches the agent when to use them. Use both for the best behavior.

Try it with nothing installed and a throwaway DB: uvx --from yggdrasil-memory ygg serve --reset --db /tmp/ygg.sqlite.

Then just work: ask your agent "recall what we decided about this project", tell it "remember this decision" — next session it's already there. Verify the install any time with ygg doctor.

Already have history? Seed memory from your existing Claude Code + Codex transcripts, Obsidian vaults, and CLAUDE.md repos — distilled locally:

ygg seed --dry-run    # see what it would import; drop the flag to distill for real

Leaving another memory tool? ygg import --from mcp-memory --path memory.json pulls its whole store into Yggdrasil (deduped, secret-guarded) — then you can delete it.

Related MCP server: agentmem

Why

• 🧠 Persistent — decisions, lessons, and project status survive across sessions.

• 🔌 One brain, every tool — Claude Code, Codex, and any MCP host share the same memory.

• 🌐 Cross-project recall — "this looks like what you did in project B — reuse it?"

• 🧹 Curated, not captured — your agent saves the few things that matter; governance dedupes and archives, never deletes.

• 🌱 Self-maintaining (opt-in) — a small local model consolidates memory in the background. Zero API tokens.

• 🪪 One identity everywhere — an optional name and persona every agent picks up, so Claude Code and Codex feel like the same assistant.

• 🔒 100% local — your memory lives on your machine. No cloud, no account, no telemetry.

🧠 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 …).

• 🪝 Hooks — session start auto-injects identity, project status, and open follow-ups (~300 tokens); an optional per-prompt hook auto-recalls memory relevant to each request.

• 📌 Ranking — pinned and frequently-recalled memories surface first.

• 🧹 Governance — duplicates and conflicts are queued for review; changes are non-destructive (archive, never delete).

• 📓 Obsidian — every memory doubles as a plain-Markdown note you can read, edit, and grep.

🎛️ Memory tiers — zero-config by default

Out of the box, Yggdrasil runs on SQLite + FTS5 with zero dependencies — instant keyword search, no models, nothing to download. Optional local models via Ollama add two independent tiers:

Ollama only computes vectors and runs the background model — every memory and every vector stays in the same local SQLite. ygg install detects your hardware and recommends a fit (ygg recommend shows the full catalog).

Embeddings (semantic search):

Background consolidation (small LLM):

The engine itself is swappable — any service meeting the MemoryBackend contract is a drop-in (YGG_ENGINE_URL); see docs/backend-boundary.md.

📊 The numbers

Measured by eval/ygg_eval.py — 35 labelled queries, ranking weights tuned on the dev split only, so holdout is the unbiased number (recall@1, with the paraphrase-multilingual model):

recall@3 = 1.00 in both views — with the local model the right memory is always in the top 3, even searching the entire store; it's #1 0.93 of the time within a project. Zero-dep lexical mode already solves keyword and code-identifier queries (1.00). Small corpus (n=35), so the full breakdown in BENCHMARKS.md shows 95% CIs, pool sizes, and per-class scores — and you can rerun it in a minute: python3 eval/ygg_eval.py --report.

🆚 Yggdrasil vs the rest

Everyone else either auto-captures transcripts or sells you a cloud. Yggdrasil's bet: keep the few things that matter, curated and de-duped, in plain rows you own — and share them across every tool and project.

Closest neighbor — claude-mem: capture-everything memory that records and AI-compresses every session (Node 20+ and Bun, a persistent worker daemon; Chroma optional). Yggdrasil is the opposite bet: a small, high-signal store instead of a growing firehose. mem0 is an SDK plus a hosted platform for building apps that remember their users — even self-hosted it needs an LLM API key. Built-in memories are genuinely useful — and structurally siloed: one vendor, one repo, one machine, literal grep. Yggdrasil is the layer above them (and ygg seed can bootstrap itself from those same transcripts). Different layer entirely: context-mode (live context window) and Context7 (fresh library docs) — both pair fine with Yggdrasil.

🧰 Commands

Agents see six MCP tools: ygg_health, ygg_bootstrap, ygg_search, ygg_recall, ygg_remember, ygg_materialize — auto-registered by the plugin or ygg install.

Memory ops

Cold start

Service & setup

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

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

Heavy seeding, weak laptop? Point distillation at any box on your LAN — a desktop with Ollama, LM Studio, llama.cpp, even an iPhone running a local-LLM server app: ygg config set distill_url http://<box>:11434. Yggdrasil auto-detects the API dialect (Ollama or OpenAI-compatible); your data still never leaves your network — details in docs/ygg-cli.md.

❓ FAQ

Built-in memories are per-vendor, per-repo, per-machine, and retrieved by literal text match. Yggdrasil is the layer above: the same memory in Claude Code, Codex, and any MCP host, recall across projects, optional semantic search — still 100% local. It bridges them both ways: ygg seed distills your existing native memory + transcripts into the shared brain, and ygg export-native writes a curated digest back into AGENTS.md/MEMORY.md — so even a fresh clone or a tool without Yggdrasil still gets your curated memory.

No. The engine, the database, and the optional models all run locally. No account, no telemetry. The only outbound call is a version check against PyPI.

No — by design. Retrieval is automatic; writing is deliberate (the agent calls ygg_remember for durable lessons). Capture-everything pollutes memory and burns tokens, so we don't. The optional background model consolidates what's already saved (propose-only).

No. The default is pure lexical search — zero dependencies, instant. Semantic search is opt-in and uses a local model via Ollama. The installer recommends one that fits your hardware.

The engine idles at ~21 MB RAM (lexical default) with ~0% CPU; disk is tens of KB per memory. Session start injects ~300 tokens; each tool call returns a small snippet. All heavy work (indexing, embeddings, consolidation) runs off-LLM on your machine.

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

🚦 Status & roadmap

Alpha. The happy path and the governance loop are gate-tested (scripts/run_gates.sh); not yet hardened for multi-user or production use. macOS today; Linux/Windows service installers are built and in final on-device testing.

Next: 🛰️ cross-surface sync (one memory across CLI, web, and phone) · 🔗 relation graph (SOLVES / SUPERSEDES / CONTRADICTS) · 🐧 Linux/Windows GA.

🤝 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

GNU AGPL v3.0 — see LICENSE. Free and open source: use, modify, self-host, redistribute. If you modify it or offer it as a network service, you must release your source under the same license.