Metadata-Version: 2.4
Name: yggdrasil-memory
Version: 0.3.0
Summary: One shared, durable memory for all your AI coding agents — MCP, local-first, zero-dependency.
Project-URL: Homepage, https://github.com/VonderVuflya/yggdrasil
Project-URL: Repository, https://github.com/VonderVuflya/yggdrasil
Project-URL: Issues, https://github.com/VonderVuflya/yggdrasil/issues
Author: Yggdrasil contributors
License: Yggdrasil is licensed under the Elastic License 2.0.
        
        Copyright (c) 2026 Yggdrasil contributors (the "Licensor").
        
        Canonical text: https://www.elastic.co/licensing/elastic-license
        
        -------------------------------------------------------------------------------
        
        Elastic License 2.0
        
        ## Acceptance
        
        By using the software, you agree to all of the terms and conditions below.
        
        ## Copyright License
        
        The licensor grants you a non-exclusive, royalty-free, worldwide,
        non-sublicensable, non-transferable license to use, copy, distribute, make
        available, and prepare derivative works of the software, in each case subject to
        the limitations and conditions below.
        
        ## Limitations
        
        You may not provide the software to third parties as a hosted or managed
        service, where the service provides users with access to any substantial set of
        the features or functionality of the software.
        
        You may not move, change, disable, or circumvent the license key functionality
        in the software, and you may not remove or obscure any functionality in the
        software that is protected by the license key.
        
        You may not alter, remove, or obscure any licensing, copyright, or other notices
        of the licensor in the software. Any use of the licensor's trademarks is subject
        to applicable law.
        
        ## Patents
        
        The licensor grants you a license, under any patent claims the licensor can
        license, or becomes able to license, to make, have made, use, sell, offer for
        sale, import and have imported the software, in each case subject to the
        limitations and conditions in this license. This license does not cover any
        patent claims that you cause to be infringed by modifications or additions to
        the software. If you or your company make any written claim that the software
        infringes or contributes to infringement of any patent, your patent license for
        the software granted under these terms ends immediately. If your company makes
        such a claim, your patent license ends immediately for work on behalf of your
        company.
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part of the software from you
        also gets a copy of these terms.
        
        If you modify the software, you must include in any modified copies of the
        software prominent notices stating that you have modified the software.
        
        ## No Other Rights
        
        These terms do not imply any licenses other than those expressly granted in
        these terms.
        
        ## Termination
        
        If you use the software in violation of these terms, such use is not licensed,
        and your licenses will automatically terminate. If the licensor provides you
        with a notice of your violation, and you cease all violation of this license no
        later than 30 days after you receive that notice, your licenses will be
        reinstated retroactively. However, if you violate these terms after such
        reinstatement, any additional violation of these terms will cause your licenses
        to terminate automatically and permanently.
        
        ## No Liability
        
        *As far as the law allows, the software comes as is, without any warranty or
        condition, and the licensor will not be liable to you for any damages arising
        out of these terms or the use or nature of the software, under any kind of legal
        claim.*
        
        ## Definitions
        
        The **licensor** is the entity offering these terms, and the **software** is the
        software the licensor makes available under these terms, including any portion of
        it.
        
        **you** refers to the individual or entity agreeing to these terms.
        
        **your company** is any legal entity, sole proprietorship, or other kind of
        organization that you work for, plus all organizations that have control over,
        are under the control of, or are under common control with that organization.
        **control** means ownership of substantially all the assets of an entity, or the
        power to direct its management and policies by vote, contract, or otherwise.
        Control can be direct or indirect.
        
        **your licenses** are all the licenses granted to you for the software under
        these terms.
        
        **use** means anything you do with the software requiring one of your licenses.
        
        **trademark** means trademarks, service marks, and similar rights.
License-File: LICENSE
Keywords: ai-agents,claude,codex,local-first,mcp,memory,obsidian,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.VonderVuflya/yggdrasil -->
<h1 align="center">🌳 Yggdrasil</h1>

<p align="center"><b>One shared, durable memory for all your AI coding agents.</b><br/>
Claude Code, Codex, and any MCP host remember your projects — decisions, lessons, status — across sessions, tools, and projects.</p>

<p align="center">
  <img src="https://img.shields.io/badge/License-Elastic%202.0-blue.svg" alt="Elastic License 2.0">
  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/deps-zero%20(stdlib)-brightgreen" alt="zero deps">
  <img src="https://img.shields.io/badge/MCP-Claude%20·%20Codex%20·%20any%20host-purple" alt="MCP">
  <img src="https://img.shields.io/badge/local--first-100%25%20private-success" alt="local-first">
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="alpha">
</p>

<p align="center">
  <a href="#-quickstart">Quickstart</a> ·
  <a href="#-how-it-works">How it works</a> ·
  <a href="#%EF%B8%8F-commands">Commands</a> ·
  <a href="#-faq">FAQ</a> ·
  <a href="#-yggdrasil-vs-alternatives">Comparison</a>
</p>

<p align="center">
  <a href="./README.md"><img src="https://img.shields.io/badge/README-English-blue" alt="English"></a>
  <a href="./i18n/README.ru.md"><img src="https://img.shields.io/badge/docs-Русский-darkblue" alt="Русский"></a>
  <a href="./i18n/README.zh.md"><img src="https://img.shields.io/badge/docs-简体中文-red" alt="简体中文"></a>
  <a href="./i18n/README.es.md"><img src="https://img.shields.io/badge/docs-Español-orange" alt="Español"></a>
  <a href="./i18n/README.fr.md"><img src="https://img.shields.io/badge/docs-Français-blue" alt="Français"></a>
</p>

---

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 quietly learns from your work in the background.

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

🌳 Yggdrasil  (injected automatically at session start)
   You are Yggdrasil — your persistent assistant across tools and projects.
   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.

## ❌ Without Yggdrasil

- 🔁 You re-explain project context to the AI in every new chat.
- 🧩 Lessons learned in one project never reach the next one.
- 🤖 Switch from Claude Code to Codex → the new tool knows nothing.
- 🗑️ Hard-won debugging insights vanish when the session ends.

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

## 🚀 Quickstart

> **Requirements:** macOS, Python 3.10+ *(or let `uv`/`npx` fetch Python for you)*. Optional (for semantic search): [Ollama](https://ollama.com).

Install with whatever you already use — **every channel installs the same engine:**

| Tool | Command |
| --- | --- |
| **uv** _(recommended)_ | `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` |
| **from source** | `uvx --from git+https://github.com/VonderVuflya/yggdrasil.git ygg install` |

> Registry channels go live as each is published (see [RELEASING.md](./RELEASING.md)); the **from source** line works against this repo today. `npx` and `uvx` can fetch Python for you.

That's it. `ygg install`:
1. 🔍 detects your CPU/RAM/GPU and **recommends models that fit your machine** (or choose `none` for a zero-config, lexical-only setup),
2. 🔑 generates a private auth token (never hardcoded),
3. 🛎️ installs an always-on background service (auto-starts at login, restarts on crash),
4. 🤝 registers the memory tools with **Claude Code and Codex**,
5. 🪝 (optional) enables a session-start hook that auto-injects your project memory.

Check the install any time with `ygg doctor`; upgrade later with `ygg update`.

Prefer to just try the engine first, without installing a service?

```bash
uvx --from git+https://github.com/VonderVuflya/yggdrasil.git ygg serve --reset --db /tmp/ygg.sqlite   # runs on :42069
```

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

```text
   Claude Code / Codex / any MCP host
                 │   (MCP tools: ygg_search, ygg_recall, ygg_remember … )
                 ▼
        ┌─────────────────────┐      SessionStart hook injects
        │  Yggdrasil engine    │◀──── identity + project memory + open follow-ups
        │  (always-on daemon)  │
        │  SQLite + FTS5       │      background local model (optional)
        │  + optional vectors  │────▶ dedupes / links / consolidates memory
        └─────────────────────┘
                 │ materializes to
                 ▼
          📓 Obsidian vault (human-readable, editable)
```

- **Engine** — a stdlib-only HTTP server over SQLite + FTS5. Zero dependencies, ~21 MB RAM.
- **Retrieval** — lexical by default; add a local embedding model for semantic + cross-lingual search.
- **Governance** — duplicates / stale / conflicting memories are surfaced for review; changes are non-destructive (archive, never delete).
- **Obsidian** — every memory is also a Markdown note you can read and edit.

## ⭐ Features

- 🧠 **Durable cross-session memory** for any MCP-compatible agent.
- 🌐 **Cross-project recall** + a proactive "you solved this before" contract.
- 🔎 **Hybrid retrieval** — BM25 + optional dense embeddings, fused; cross-lingual (e.g. EN↔RU).
- 🪪 **Identity / persona** injected every session (the "Jarvis feel").
- 📌 **Status & follow-ups** surfaced at session start — *"what's the status of X?"* answers instantly.
- 🌱 **Background self-learning** — a small local model consolidates memory (propose-safe by default).
- 🧹 **Governance loop** — review queue + non-destructive archive/merge.
- 📓 **Obsidian materialization** — readable, editable, portable.
- 🔒 **Local-first & private** — no cloud, no account, your data stays put.
- 🪶 **Zero hard dependencies** — pure Python stdlib; optional local models via Ollama.

## 🛠️ Commands

**Memory ops — `ygg <command>`** (agent-facing)

| Command | What it does |
| --- | --- |
| `health` | Check the engine is alive |
| `bootstrap --project P` | Pull a project's memory before starting work |
| `search --project P --query "…"` | Project-scoped search (`--type`, `--limit`, `--json`) |
| `recall --query "…"` | **Cross-project** search — "have I done this anywhere?" |
| `remember --project P --type debugging_lesson --content "…"` | Save a durable memory (secret-guarded, deduped) |
| `materialize --id ID --project P` | Export one memory to an Obsidian note |

**Service & setup — `ygg <command>`** (lifecycle)

| Command | What it does |
| --- | --- |
| `install` | Guided wizard → background service + MCP registration |
| `recommend` | Show the hardware-aware model catalog |
| `status` · `start` · `stop` · `restart` · `logs` | Manage the always-on daemon |
| `hooks` · `unhooks` | Enable/disable the SessionStart auto-bootstrap hook |
| `consolidate` · `unconsolidate` | Schedule/remove background memory consolidation |
| `token` · `uninstall` | Print the auth token · remove service + registration |

**MCP tools** (what agents see): `ygg_health`, `ygg_bootstrap`, `ygg_search`, `ygg_recall`, `ygg_remember`, `ygg_materialize`.

## 🔌 Use it with your agent

- **Claude Code** — after `ygg install`, the tools are registered (`/mcp` shows `yggdrasil`) and the SessionStart hook auto-injects memory. Just open a project and work.
- **Codex** — registered too; approve the `ygg_*` tool call once per session.
- **Any MCP host** — point it at `ygg mcp` (stdio) with `YGG_ENGINE_URL` + `YGG_ENGINE_TOKEN`.

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

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

## 📊 Footprint & quality

**Footprint** (measured, 13 memories): **~21 MB RAM**, **~0% idle CPU**, **zero dependencies** (Python 3.10+ stdlib). Disk ≈ tens of KB per memory. Dense search is optional and adds a local Ollama model (e.g. `all-minilm`, 45 MB).

**Retrieval quality** (`eval/ygg_eval.py`, 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). 35 labelled cases across a dev/holdout split. Run it yourself: `python3 eval/ygg_eval.py`.

## ❓ FAQ

<details>
<summary><b>Does it send my code or memory to the cloud?</b></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><b>How is this different from Context7 / RAG over docs?</b></summary>

Context7 fetches up-to-date <i>public library docs</i> (the latest React/Next.js API). Yggdrasil remembers <i>your own work</i> — your decisions, lessons, and project status. They're complementary; run both. See <a href="#-yggdrasil-vs-alternatives">comparison</a>.
</details>

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

No — by design. Retrieval is automatic; <i>writing</i> is deliberate (the agent calls <code>ygg_remember</code> 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>

<details>
<summary><b>Do I need a GPU or an API key?</b></summary>

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

<details>
<summary><b>How many tokens does it cost my agent?</b></summary>

Very few. Session start injects ~300 tokens of memory; each tool call returns a small snippet. All the heavy work (indexing, embeddings, consolidation) runs off-LLM on your machine.
</details>

<details>
<summary><b>Can I edit or delete memories by hand?</b></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><b>Is it production-ready?</b></summary>

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

## 🆚 Yggdrasil vs alternatives

Most "AI memory/context" tools own a **different layer** of the stack. The one nobody filled — **durable, cross-session, cross-agent memory of _your own_ work** — is exactly where Yggdrasil sits. It doesn't compete with these; it's the memory they all plug into.

| Tool | The layer it owns | Overlap with Yggdrasil | Better together |
| --- | --- | --- | --- |
| **[Context7](https://github.com/upstash/context7)** | fresh public **library docs** (read-only) | none | Context7 gives a library's current API; Yggdrasil recalls *your* decisions & lessons |
| **[autoresearch](https://github.com/karpathy/autoresearch)** | autonomous **experiment loop** (edit → train → measure → keep/revert) | none — it's the *loop*, not memory | Yggdrasil is the long-term memory the loop lacks: recall what you already tried, remember each result across nights & forks → [integration](./integrations/autoresearch/) |
| **context-mode** & in-context compressors | **in-session** context compaction / sandboxed analysis | none — per session | Yggdrasil persists the *conclusions* across sessions, tools & machines |
| **plain LLM memory** | per-session scratch | partial | Yggdrasil is durable, cross-project, governed & local |

Capability matrix:

| | **Yggdrasil** | Context7 | Plain LLM memory |
| --- | --- | --- | --- |
| Knows **your** decisions/lessons | ✅ | ❌ | ⚠️ within one session |
| Up-to-date public library docs | ❌ (use Context7) | ✅ | ❌ |
| Cross-session & cross-**agent** | ✅ | ✅ | ❌ |
| Cross-**project** recall | ✅ | — | ❌ |
| Writes/accumulates your memory | ✅ | ❌ (read-only) | ⚠️ |
| Local & private | ✅ | ☁️ hosted | depends |
| Self-consolidating | ✅ | ❌ | ❌ |

**TL;DR:** these tools fetch docs, run experiments, or compress one session. **Yggdrasil is the durable memory of _your own_ work that they were all missing — use it *with* them and you only win.**

## 🗺️ Roadmap

- 🔗 Relation graph (`SOLVES` / `SUPERSEDES` / `CONTRADICTS`) for richer reasoning.
- 🛰️ Multi-device sync — continue literally from any machine.
- 🧪 Stronger optional models for safe autonomous consolidation.
- 🐧 Linux/Windows service installers (currently macOS launchd).

## 🤝 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](./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.
