yggdrasil-memory 0.1.0__tar.gz

yggdrasil_memory-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# --- Runtime / data (never commit) ---
+data/
+reports/
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+*.db
+*.log
+*.pid
+
+# --- Generated vault notes (runtime output; may contain private memory) ---
+# Keep the folder structure (.gitkeep), ignore generated notes.
+vault/04-learnings/*.md
+vault/99-review/*.md
+
+# --- Stray runtime artifacts ---
+debugging_lesson_record.json
+
+# --- Python / tooling / OS ---
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+# npm launcher bundles LICENSE only at publish time (copied from repo root)
+clients/npm/LICENSE
+clients/npm/*.tgz
+node_modules/
+.venv/
+venv/
+node_modules/
+.DS_Store
+.pytest_cache/

yggdrasil_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); versioning is [SemVer](https://semver.org/).
+
+## [0.1.0] — 2026-06-18
+
+First public release. An alpha but honest one: the happy path and the full
+governance loop are covered by passing gates (`scripts/run_gates.sh`).
+
+### Added
+- **Own memory engine** — stdlib-only HTTP server over SQLite + FTS5, zero
+  dependencies (~21 MB RAM), behind a swappable `MemoryBackend` contract.
+- **Agent integration** — MCP facade (`ygg_health`, `ygg_bootstrap`,
+  `ygg_search`, `ygg_recall`, `ygg_remember`, `ygg_materialize`) + CLI (`ygg.py`).
+- **Hybrid retrieval** — BM25 + optional local dense embeddings (via Ollama),
+  cross-lingual (EN↔RU), score-normalized fusion.
+- **Cross-project recall** + a proactive "you solved this before" contract.
+- **Always-on service** — launchd daemon (auto-start, auto-restart) + an
+  interactive installer with hardware-aware model recommendations.
+- **SessionStart hook** — injects identity/persona, project memory, and open
+  follow-ups/status into every session.
+- **Background smart write-path** — a small local model finds semantic
+  duplicates/contradictions the lexical layer misses (propose-safe by default).
+- **Governance loop** — review queue + non-destructive archive / merge /
+  verify-or-archive actions.
+- **Obsidian materialization** + a Claude-memory importer.
+- **Eval harness** (recall@k / MRR by query class) + 4 integration gates +
+  engine unit tests.
+- **Docs** — README in English / Русский / 简体中文 / Español / Français.
+- **License** — Elastic License 2.0 (source-available: free to use, modify,
+  self-host, and redistribute; no resale as a product and no offering it to
+  others as a hosted/managed service).
+
+### Notes
+- The engine is swappable: any REST service satisfying the `MemoryBackend`
+  contract is a drop-in (point `YGG_ENGINE_URL` at it). Yggdrasil ships its own.
+- Auto-applying background consolidation is opt-in; the safe default only
+  proposes (a small local model can mislabel distinct-but-similar lessons).

yggdrasil_memory-0.1.0/LICENSE

@@ -0,0 +1,99 @@
+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.

yggdrasil_memory-0.1.0/PKG-INFO

@@ -0,0 +1,389 @@
+Metadata-Version: 2.4
+Name: yggdrasil-memory
+Version: 0.1.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
+
+<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.63 | 0.00 | 0.00 |
+| dense · `all-minilm` (45 MB, EN) | 0.75 | 0.67 | 0.00 |
+| dense · `paraphrase-multilingual` (~560 MB) | **0.94** | 0.67 | **1.00** |
+
+`keyword` and `identifier` queries are 1.0 in every mode. 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.