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

Related MCP server: Mnemo Cortex

🚀 Quick Start

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.

Option A — install as a plugin (one step, right inside your agent — zero-config). In Claude Code:

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

Option B — install the full service (always-on daemon + auto-inject at session start + optional local models):

uvx --from yggdrasil-memory ygg install      # one-time guided setup

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.

Verify & use:

ygg doctor       # engine · models · MCP registration · hook — all green?

Then just work. Ask your agent "recall what we decided about this project", or tell it "remember this decision" — and in the next session it's already there.

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

ygg seed --dry-run    # see what it'd import; drop --dry-run to distill for real

Just kicking the tyres? uvx --from yggdrasil-memory ygg serve --reset --db /tmp/ygg.sqlite.

🔌 More ways to connect

Beyond the plugin and ygg install above:

• 🖥️ 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

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.

Embeddings (semantic search):

Background consolidation (small LLM):

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

The closest tool is claude-mem — also durable memory for coding agents, but a heavier, capture-everything system: it auto-records every session and AI-compresses it (needs Node + Bun + a vector DB). mem0 is a memory SDK for apps to remember their users. context-mode and Context7 own different layers (your live context window; fresh library docs). Yggdrasil is install-and-go, zero-dependency, local-first memory of your own work — curated, not a firehose, stored as plain Markdown you can edit.

claude-mem vs Yggdrasil, in one line: claude-mem auto-captures everything and AI-compresses it (Node + Bun + a vector DB; ~84k★, ships a crypto token) — the store grows with every session. Yggdrasil keeps the few things that matter — curated and semantically de-duped (near-identical lessons collapse, so it stays small and high-signal), zero-dependency, stored as plain rows you can grep, edit, and own — no AI required, no token. Different philosophy; you can run both.

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: want automatic capture-everything across many IDEs and don't mind a heavier stack → claude-mem. Building an AI product that must remember its users at scale → mem0. Want a tiny, local, curated memory you own — zero deps, no AI required — for the coding agents you already use → 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.

Memory ops

Cold start — seed from your existing work

Big sessions can be slow on a tiny model — point distillation at a beefier box on your LAN (Configuration ↓):

ygg seed --ollama-url http://192.168.3.124:11434 --model llama3.2:3b --timeout 240

Service & setup

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

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

⚙️ Configuration

Yggdrasil works with zero config. When you do want to change something, every setting resolves the same way:

--flag > environment variable > ~/.yggdrasil/config.json > default

Use a flag for one run, or ygg config set to make it stick:

ygg config list                       # effective values + where each one comes from
ygg config set distill_timeout 240    # persist a setting
ygg config get distill_url
ygg config unset bg_model             # back to the default

Distill on another machine. Distillation (ygg seed) is heavy but occasional; embeddings are light but constant. So distill_url is deliberately kept separate from embed_url — send distillation to a powerful box on your LAN while embeddings (and your data) stay local and always-on:

# on the beefy box (B): expose Ollama to the LAN + pull the model
OLLAMA_HOST=0.0.0.0:11434 ollama serve
ollama pull llama3.2:3b

# on your laptop (A): make B the default distill endpoint
ygg config set distill_url http://192.168.3.124:11434
ygg config set bg_model    llama3.2:3b
ygg seed     # distills on B; your SQLite DB + embeddings never leave A

❓ FAQ

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

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

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.

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.

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

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

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

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.

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

GNU AGPL v3.0 — see LICENSE. Free and open source (OSI-approved): you may use, modify, self-host, and redistribute Yggdrasil. Under the AGPL's network copyleft, if you modify it or offer it to others as a hosted/network service, you must release your source under the same license.