Tree-Ring-Memory
AGENTS.md18 starsChanged 3 months agoMITView on GitHub
Read .tree-ring/AGENTS.md, .tree-ring/SKILL.md, and .tree-ring/CLI.md before substantive work. The project lifecycle hook runs receipt-backed recall at session boundaries and one strict automatic capture checkpoint before a session or subagent turn stops. Do not claim memory is active without a valid project-local recall receipt. Capture zero to three concise durable candidates; never store a transcript or invent memory. <!-- tree-ring:end codex --> Clean checkout: the marked memory preflight above applies when the generated .tree-ring/AGENTS.md, SKILL.md, and CLI.md exist. If they are…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository8 other files it gives its agents.
- crates/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- fixtures/AGENTS.mdAGENTS.md
- marketing/AGENTS.mdAGENTS.md
- plugins/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- docs/llms.txtllms.txt
- tree-ring-memorySkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Read this root file and identify the paths involved in the task.
- Distinctive: line 37
After meaningful changes, review the owning document and its parents.
- Distinctive: line 42
Create a child at a durable responsibility boundary.
- Distinctive: line 47
Before finishing, re-check changed paths against the hierarchy, run relevant existing verification, and report intentionally unchanged docs …
- Distinctive: line 54
Keep both sets of instructions: preserve existing root content and Tree Ring's small marked reference block.
- Distinctive: line 62
Keep behavior in the Rust core, SQLite implementation, and shared CLI actions.
- Distinctive: line 70
Run host probes for lifecycle changes and verify published archive checksums for releases.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- tree-ring:begin codex v1 -->Tree Ring Memory
Read .tree-ring/AGENTS.md, .tree-ring/SKILL.md, and .tree-ring/CLI.md before substantive work. The project lifecycle hook runs receipt-backed recall at session boundaries and one strict automatic capture checkpoint before a session or subagent turn stops. Do not claim memory is active without a valid project-local recall receipt. Capture zero to three concise durable candidates; never store a transcript or invent memory.
<!-- tree-ring:end codex -->Clean checkout: the marked memory preflight above applies when the generated
.tree-ring/AGENTS.md, SKILL.md, and CLI.md exist. If they are absent, treat
Tree Ring memory as inactive and continue with this tracked repository contract
and its DOX hierarchy. Initialize local memory only when setup is authorized;
missing generated files do not block ordinary repository work.
Tree Ring Memory repository
Tree Ring is a Rust workspace for local, lifecycle-aware agent memory. Read
README.md for commands and docs/protocol/harness-activation.md for activation.
Root ownership covers Cargo manifests, install.sh, schemas, shared assets,
marketplace descriptors, .github/workflows, and the canonical skills/ guide.
DOX framework
This repository uses agent0ai/DOX, adapted from
revision 765ae4ac02cc884eefcd41a3d0f71941721adb89 as its project instruction hierarchy. See upstream MIT license.
Read before editing
- Read this root file and identify the paths involved in the task.
- Walk from the root to each target, reading every applicable child
AGENTS.mdand following its Child DOX Index before editing. - Parent contracts remain in force. The nearest child adds local detail; it cannot weaken the DOX workflow or repository-wide authority and safety rules.
- Re-read the applicable chain in the current session. Recalled memory is a navigation aid, never a substitute for the current source and instructions.
Keep the hierarchy current
After meaningful changes, review the owning document and its parents. Update purpose, ownership, contracts, workflows, inputs, outputs, side effects, and verification when they change. Refresh affected child indexes and remove stale or contradictory text. Document durable rules, not session transcripts.
Create a child at a durable responsibility boundary. Use these sections in order: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index. Guidance and verification describe existing requirements and checks; leave them empty when none exist rather than inventing gates.
Before finishing, re-check changed paths against the hierarchy, run relevant existing verification, and report intentionally unchanged docs with the reason.
Instruction and memory separation
The root and child DOX files describe this repository. .tree-ring/AGENTS.md,
.tree-ring/SKILL.md, and .tree-ring/CLI.md describe the local memory runtime.
Keep both sets of instructions: preserve existing root content and Tree Ring's
small marked reference block. Never replace one AGENTS.md with the other.
Local memory databases, receipts, private credentials, and generated runtime
files are not DOX documents to publish. Installed third-party skills retain
their own instructions; do not recursively rewrite their contents.
Work and verification
Keep behavior in the Rust core, SQLite implementation, and shared CLI actions. Preserve project-local storage, identity scopes, privacy filtering, create-only bridge publication, and receipt-backed activation. A binary, plugin, configured hook, or marker alone does not prove live memory use.
For runtime changes run cargo test --workspace --locked and
cargo fmt --all -- --check. Package changes use
python3 scripts/validate-plugin-packages.py; installer edits use sh -n install.sh.
Run host probes for lifecycle changes and verify published archive checksums for
releases. Report source, packaged release, installed runtime, actual hook proof,
and external marketplace submission as distinct outcomes.
Child DOX Index
- crates/AGENTS.md — Rust workspace and crate boundaries.
- plugins/AGENTS.md — Codex and Claude packaging and lifecycle hooks.
- scripts/AGENTS.md — Validation, certification, installer and release tooling.
- docs/AGENTS.md — Published documentation, protocol contracts and design records.
- fixtures/AGENTS.md — Synthetic acceptance, parity and quality data.
- marketing/AGENTS.md — Campaign source material and visual assets.
- templates/dox/AGENTS.md — Existing downstream Tree Ring project-contract template; not this repository’s root contract.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.