# Rehydrate before the agent reads a single file
nool status --compact
nool log --limit 5 --compact
nool context "add rate limiting to the public API" --budget 4000 --cite
# Take a lease on the scope, then let Claude Code work
nool announce intent --intent "Add rate limiting to the public API without changing auth middleware" --target-nodes src/middleware/rateLimit.ts
# Land the change with the same intent, sealed into the ledger
nool propose --path src/middleware/rateLimit.ts --path src/server.ts --intent "Add rate limiting to the public API without changing auth middleware"
nool solidify --compact
# Leave the reasoning for the next session
nool learn --about rate-limiting --scope api --kind reasoning_note \
--content "Limits live in middleware, not per route; per-route limits were rejected because they bypass the shared quota."The same commands work from a terminal, a Claude Code hook, or the Nool MCP server. The next session runs nool log and nool findings and starts where this one stopped.
Why Claude Code forgets
A Claude Code session is bounded by its context window and ends when the terminal closes. CLAUDE.md and auto-memory carry preferences and conventions, but they are prose an agent reads at start-up, not a record of what changed, why it changed, and what was decided last Tuesday. So the next session re-derives: it re-reads the code, rediscovers the constraint you already explained, and sometimes reverses a decision because the reasoning was never written anywhere it would look. Handing a session to a colleague or to a second agent is worse. Whatever the first session learned is gone unless someone pasted it into a document, and documents drift from the code within days. The symptom teams report is not that Claude Code is weak; it is that every session starts from zero on a codebase that has a history.
What Nool remembers, and where it lives
Nool keeps a ledger inside the repository, in the .nool directory, mirrored to Git. Every change lands as a knot that carries the declared intent, the computed blast radius and the evidence that justified it. Alongside the knots, findings record what the team learned: root causes, dependency insights and reasoning notes, each attached to a subject and optionally to a scope such as billing or mobile-ios. A finding can supersede an earlier one, so a decision that was replaced comes back marked as replaced rather than as current. Because the ledger lives with the code, it survives sessions, machines and vendors. A Codex or Cursor session can read what a Claude Code session recorded, and a new engineer can ask why a module looks the way it does and get the causal chain, not a guess.
How a Claude Code session starts with Nool
The loop is short. nool status shows the state of the ledger and any active leases. nool log rehydrates the last few knots, so the agent sees what the previous session landed and why. nool context assembles a budgeted packet for the task at hand: the matching entities, their blast radius, prior findings and, if asked, AST skeletons with bodies elided, inside a token budget you set. The agent then announces its intent, which takes a lease on the files it will touch, does the work, and proposes the change with the same intent it announced. Solidify seals the knot. Anything worth keeping for next time goes in with nool learn. With the Nool MCP server configured, Claude Code makes these calls itself; from a plain terminal the commands are the same.
What the benchmark says about memory
The coordination benchmark includes a memory arm built to answer one question: which decision is still current? Eleven decisions with thirteen clauses were probed twelve times, with hand-authored expected answers as ground truth. Reading the code with no durable memory, flat retrieval over documents, temporal retrieval with a metadata filter, and the Nool ledger were compared against a hand-written causal resolver used as a ceiling. The Nool ledger had the highest precision of any shippable arm, nearly double flat retrieval, and cut stale answers from sixteen to six. It did not have the highest recall; the hand-written ceiling still resolved more probes. The honest claim is that a ledger with scope and supersession beats retrieval-based memory, not that it is the best conceivable resolver.
Set it up in ten minutes
Install the CLI with the one-line installer, run nool init --from-git main inside the repository, and let nool discover features build the architecture model. From there you have two ways to connect Claude Code. The simplest is the terminal: run nool status and nool log at the start of a session and nool learn at the end, or put those calls in Claude Code hooks so they happen without thinking. The tighter integration is the Nool MCP server, documented under docs, which exposes context, findings, announce and propose as tools Claude Code calls itself. In the first week the ledger is thin and the benefit is mostly the envelope check. By the second week the findings you recorded start coming back in nool context, and that is when sessions stop starting from zero.
Frequently asked questions
- Does Nool replace CLAUDE.md?
- No. CLAUDE.md tells Claude Code how you want it to behave. Nool records what actually happened to the repository and what was decided along the way. Keep the instructions file for conventions and use the ledger for history, findings and intent. The two are complementary, and the MCP server lets Claude Code read the ledger without any change to CLAUDE.md.
- Where is the memory stored, and does it leave my machine?
- In the .nool directory of the repository, mirrored to Git so it travels with clones and pushes. Nool runs locally and verifies its licence locally. Syncing to a Nool hub for multi-machine leases is opt-in; nothing phones home by default.
- Can Codex, Cursor or Gemini CLI read what Claude Code recorded?
- Yes. The ledger is vendor-neutral. Any agent that can run the CLI or call the MCP server gets the same nool log, nool findings and nool context, so a task started in Claude Code can be picked up in Cursor with the reasoning intact.
- What happens when the context window fills mid-task?
- Nothing is lost that was recorded. The announced intent, the lease, any proposed knots and any findings are in the ledger. Start a new session, run nool log and nool context for the same task, and continue. Recording a finding before you stop is the habit that makes this painless.
- How do I hand a task from Claude Code to a colleague or another agent?
- Record the state before you stop: nool announce with-context captures the decisions and constraints you settled on, nool learn records anything reusable, and nool thread handoff passes an intent thread on explicitly. The next person or agent runs nool log and nool context for the same task and picks up with the reasoning intact.