yggdrasil-memory 0.4.3

One shared, durable memory for all your AI coding agents — MCP, local-first, zero-dependency.

🌳 Yggdrasil

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.

Quick Start · How it works · Compare · Commands · FAQ

---

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.

🚀 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

Every install channel (same engine)

Host / tool	Command
Claude Code · Codex · Cursor (plugin)	/plugin marketplace add VonderVuflya/Yggdrasil → /plugin install yggdrasil
uvx (recommended CLI)	uvx --from yggdrasil-memory ygg install
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
Claude Desktop (app)	drag the .mcpb from the latest release onto Settings → Extensions (guide)
from source	uvx --from git+https://github.com/VonderVuflya/yggdrasil.git ygg install

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.

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

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.

Full model menu (or run ygg recommend)

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

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.

	Yggdrasil	claude-mem	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	✅	✅
Zero dependencies (stdlib + SQLite; no Node/Bun/vector DB)	✅	❌	❌	❌	—
Works with no LLM & no API key (lexical default)	✅	❌ AI-compresses	❌ needs an LLM	✅	❌
Curated & editable as plain Markdown (not capture-everything)	✅	❌ auto-captures all	⚠️	❌	—
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	✅	✅
Up-to-date public library docs	❌ (use Context7)	❌	❌	❌	✅

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). Yggdrasil keeps the few things that matter — curated, deduped, zero-dependency, stored as Markdown you 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.

Full ygg CLI reference

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"] }

❓ FAQ

Does it send my code or memory to the cloud?

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

Does it automatically remember everything?

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

Do I need a GPU or an API key?

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.

How heavy is it, and how many tokens does it cost?

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.

How good is retrieval?

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

Can I edit or delete memories by hand?

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

Is it production-ready?

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

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.