Skip to content
Back to search

yewtree

MarketplaceWorks with Claude CodeGitHub

Yewtree: lossless, tree-structured project memory for coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adammostofi--yewtree/badge.svg)](/listings/adammostofi--yewtree)

HTML

<a href="/listings/adammostofi--yewtree"><img src="/api/listings/adammostofi--yewtree/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv tool install git+https://github.com/AdamMostofi/yewtree@v0.2.0

Then connect your agent (the table above), and work as usual. To look at what was recorded:

amem verify               # integrity, capture completeness, known gaps, uncertain attribution
amem state overview       # what matters now
amem knowledge topics     # decisions, bugs, constraints, by topic
amem history sessions     # every session, by every agent
amem brief                # the memory overview as a file, for agents that only read files

The key that encrypts the memory lives outside the project by default. A passphrase or the OS keychain works too: set `AMEM_KEY_SOURCE` (`key-file`, `passphrase` or `keychain`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "yewtree",
  3. "description": "Yewtree: lossless, tree-structured project memory for coding agents.",
  4. "owner": { "name": "AdamMostofi", "url": "https://github.com/AdamMostofi" },
  5. "plugins": [
  6. {
  7. "name": "yewtree",
  8. "source": "./plugins/claude-code",
  9. "description": "Lossless, tree-structured project memory with a context manager: everything is kept, only what the work needs is loaded.",
  10. "category": "productivity",
  11. "tags": ["memory", "context"]
  12. }
  13. ]
  14. }
README.md · README · 192 lines
  1. <p align="center">
  2. <img src="assets/banner.svg" alt="Yewtree: lossless, tree-structured memory for coding agents" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/AdamMostofi/yewtree/releases"><img alt="Release" src="https://img.shields.io/github/v/release/AdamMostofi/yewtree?color=2f6b45&label=release"></a>
  6. <a href="https://github.com/AdamMostofi/yewtree/actions/workflows/tests.yml"><img alt="Tests" src="https://github.com/AdamMostofi/yewtree/actions/workflows/tests.yml/badge.svg"></a>
  7. <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-2f6b45"></a>
  8. <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-2f6b45">
  9. <img alt="No network calls" src="https://img.shields.io/badge/network-none-2f6b45">
  10. <img alt="Encrypted at rest" src="https://img.shields.io/badge/archive-encrypted-2f6b45">
  11. </p>
  12. <p align="center">
  13. <b>Your coding agent forgets. Yewtree keeps everything, and shows the agent only what it needs.</b>
  14. </p>
  15. ---
  16. ## Why
  17. Long agent sessions lose things:
  18. - **Compaction** summarises the past and throws away the detail.
  19. - **A new session** starts from nothing.
  20. - **A notes file** goes stale the moment a file changes behind it.
  21. Yewtree records every prompt, tool call, reply, file version, test run and decision, losslessly, in the project
  22. itself. It keeps that record honest: it checks files against what the agent says it did, and records the gaps.
  23. Then it hands the agent a small, budgeted slice at the moments that matter:
  24. - when a session starts;
  25. - on each prompt;
  26. - right after a compaction.
  27. The rest stays one tool call away.
  28. ## How it works
  29. <p align="center"><img src="assets/how-it-works.svg" alt="The agent's hooks hand every event to the amem engine, which records it in the project's memory; memory flows back as an overview, prompt offers, a restore after compaction, and tools." width="100%"></p>
  30. - **Capture never gets in the way.** Every hook exits 0. A broken store becomes a recorded gap, never an error
  31. in the agent. A session server keeps the store open, so a hook takes tens of milliseconds.
  32. - **Nothing is trusted blindly.** Every file change is checked against what the agent reported, and labelled:
  33. - `agent_tool`: an agent's edit;
  34. - `agent_bash`: an agent's command;
  35. - `git_operation`;
  36. - `external`;
  37. - an honest `unattributed`.
  38. Test results are marked verified, stale or unknown, and say why.
  39. - **Context is a budget, not a dump.** A context manager tracks what the agent has loaded. It offloads finished
  40. work to one-line references, and restores any reference exactly.
  41. ## Four trees, one store
  42. <p align="center"><img src="assets/four-trees.svg" alt="History, Artifacts, Knowledge and State are four navigable trees over one append-only, encrypted store." width="100%"></p>
  43. Each tree answers one question and has its own navigator, and links between trees are explicit. Every record
  44. says how it is known:
  45. - **observed** by the engine;
  46. - **declared** by an agent or by you;
  47. - **inferred** by a named rule.
  48. ## Features
  49. **Capture and storage**
  50. - **Event log:** append-only, with a hash chain per writer, so tampering or loss shows up in `amem verify`.
  51. - **Archive:** compressed, encrypted (AES-256-GCM) and content-addressed. Old content is packed losslessly with
  52. lzma.
  53. - **Secrets:** redacted before anything is written. `amem purge` removes a leaked value for good, and can
  54. rotate the key.
  55. - **Where it lives:** inside the project, in `.agent-memory/`, which ignores itself in git.
  56. **Understanding the project**
  57. - **Artifacts:**
  58. - every file version, with rename and revert detection;
  59. - Python and TypeScript symbols and imports;
  60. - Markdown and reStructuredText sections and links;
  61. - full-text search.
  62. - **Knowledge:** decisions, approaches, requirements, constraints, bugs and their fixes, under a topic
  63. hierarchy, with supersession chains.
  64. - **State:** objectives, tasks, blockers, priorities, focus and next actions, with staleness and token-budgeted
  65. levels.
  66. - **Verification:** test runs recorded with the files and environment they covered.
  67. **Working with agents**
  68. - **10 memory tools over MCP:** one per tree, plus links, load and get, context (offload, restore, pin),
  69. storage, and declare.
  70. - **Protected items** (constraints, objectives, open conflicts, the current task) are never evicted silently.
  71. When they overflow, they are ranked, referenced or counted.
  72. - **Several agents in one project:** a session started in Claude Code continues in OpenCode, and every change
  73. names the agent and session that made it.
  74. - **Pi's session tree:** forks and `/tree` branches become memory branches.
  75. ## What it does, and what it doesn't
  76. | Yewtree does | Yewtree doesn't |
  77. |---|---|
  78. | Keep the full history of a project's agent sessions, losslessly | Send anything over the network: no cloud, no telemetry, no API keys |
  79. | Tell you who changed a file, or say plainly that it doesn't know | Guess: an unexplained change is `unattributed` |
  80. | Give the agent a small overview and point to the rest | Fill the context window with everything it has |
  81. | Work with any agent that has hooks, MCP or just a shell | Block, approve or slow down an agent's actions |
  82. | Prove the record is intact (`amem verify`) | Prove nothing happened before capture started |
  83. | Redact secrets it recognises | Catch every secret format (purge exists for the rest) |
  84. | Encrypt file contents and full messages | Encrypt the event log's short summaries ([SECURITY.md](SECURITY.md)) |
  85. ## Agents
  86. <p align="center"><img src="assets/tiers.svg" alt="Three tiers: hooks, MCP only, CLI only." width="100%"></p>
  87. | Agent | Tier | Connect it | Tested |
  88. |---|---|---|---|
  89. | **Claude Code** | Hooks | `claude plugin marketplace add AdamMostofi/yewtree`, then `claude plugin install yewtree@yewtree` | Replayed real sessions |
  90. | **OpenCode** | Hooks | Add `".../plugins/opencode/index.js"` to `plugin` in `opencode.json` | Live, OpenCode 1.18.35 |
  91. | **Pi** | Hooks | `pi install git:github.com/AdamMostofi/yewtree@v0.2.0` | Real runtime, Pi 1.4.0 |
  92. | **Codex** | Hooks | `codex plugin marketplace add AdamMostofi/yewtree`, install from `/plugins`, then trust its hooks in `/hooks` | Built from its docs |
  93. | **Gemini CLI** | Hooks | `gemini extensions install ./plugins/gemini` (from a clone) | Built from its docs |
  94. | **Cursor** | Hooks | `amem setup cursor` | Built from its docs |
  95. | **Windsurf, Cline** | MCP only | `amem setup windsurf` or `amem setup cline` | Built from their docs |
  96. | **Aider** | CLI only | `amem setup aider` | Built from its docs |
  97. "Built from its docs" means the adapter follows the agent's official documentation (read 2026-11-20) and passes
  98. the shared adapter suite. It has not been run against a real install yet. [docs/agents.md](docs/agents.md) has
  99. the details.
  100. ## Install
  101. ```bash
  102. uv tool install git+https://github.com/AdamMostofi/yewtree@v0.2.0
  103. ```
  104. Then connect your agent (the table above), and work as usual. To look at what was recorded:
  105. ```bash
  106. amem verify # integrity, capture completeness, known gaps, uncertain attribution
  107. amem state overview # what matters now
  108. amem knowledge topics # decisions, bugs, constraints, by topic
  109. amem history sessions # every session, by every agent
  110. amem brief # the memory overview as a file, for agents that only read files
  111. ```
  112. The key that encrypts the memory lives outside the project by default. A passphrase or the OS keychain works
  113. too: set `AMEM_KEY_SOURCE` (`key-file`, `passphrase` or `keychain`).
  114. ## Measured so far
  115. These come from the test suite and from replays of real sessions, not from a benchmark:
  116. | What | Result |
  117. |---|---|
  118. | Hook latency through the session server (replayed Claude Code sessions) | p50 36–39 ms, p95 103–150 ms |
  119. | Per event in OpenCode and Pi | 8–46 ms and 10–75 ms |
  120. | Recall on prompts that share no words with what they need (test fixture) | 20% before, 80% after task- and link-aware retrieval |
  121. | Memory overview at session start | about 390 tokens |
  122. | Tool definitions | about 1,224 estimated tokens |
  123. **The benchmark against plain compaction and against notes with git and grep is designed but not run.**
  124. [benchmark/RESULTS.md](benchmark/RESULTS.md) says why. Until it runs, there is no evidence that Yewtree reduces
  125. stale-state errors. That is the claim it exists to test.
  126. ## FAQ
  127. **Does it need an API key, a model or an account?** No. The engine runs locally with no model and no network.
  128. **Where is my data?** In `<project>/.agent-memory/`, encrypted, with the key outside the project.
  129. [SECURITY.md](SECURITY.md) lists exactly what is encrypted and what isn't.
  130. **Will it slow my agent down?** Hooks hand their data to a session server, in tens of milliseconds. If anything
  131. fails, the agent carries on and the failure becomes a recorded gap.
  132. **Can I use it with two agents at once?** Yes. Each change names the agent and session that made it. When two
  133. agents' commands could both explain a change, both are listed and neither is picked.
  134. **Why "Yewtree"?** Yews live for thousands of years and keep growing around their own past. Its logo's four
  135. branches are the four trees, growing from one root: the archive.
  136. ## Development
  137. ```bash
  138. git clone https://github.com/AdamMostofi/yewtree && cd yewtree
  139. uv sync --locked --extra dev
  140. uv run pytest -q
  141. ```
  142. **Names:** the command is `amem`, and the Python package is `agent_memory`. Yewtree was built inside
  143. [ADAM](https://github.com/AdamMostofi/ADAM) under the working name `agent-memory`, and moved here with its
  144. history. The design documents are there:
  145. - [architecture revision 3](https://github.com/AdamMostofi/ADAM/blob/master/docs/design/2026-11-13-memory-architecture-rev3.md);
  146. - the [original design](https://github.com/AdamMostofi/ADAM/blob/master/docs/design/2026-11-06-agent-memory-engine.md).
  147. ## License
  148. [MIT](LICENSE). Third-party licenses are in [THIRD_PARTY.md](THIRD_PARTY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.