Skip to content

About

Turn a project's AI memory files into a structured cube that coding agents read top-down: short summaries first, detail only when a task needs it.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Context Cube

Context Cube turns a project's AI memory files (CLAUDE.md, a long HISTORY.md, an INVARIANTS.md, design notes) into a structured memory that AI coding agents read top-down: short summaries first, detail only when a task needs it.

Why

Memory files grow until they hurt. A 5,000-line history file is either read in full at the start of every session, which spends a large share of the agent's context, or, more often, only its top is read and the older knowledge that matters gets missed.

Context Cube keeps all of it, word for word, but arranges it so an agent reads a one-line list of areas, opens the one or two areas its task touches, reads their summaries, and opens only the entries it needs. Rules that must never be broken find the agent on their own when it opens the code they govern.

Quickstart (two minutes)

You need Node 20 or newer and Claude Code, logged in: the command-line tool, or the Claude desktop app (see Without a terminal). In your project's folder, run:

npx context-cube

Until it's published to npm, run it straight from GitHub: npx github:Spobi/context-cube.

The setup:

  1. looks for files that hold project memory and tells you, in plain words, what it found;
  2. tells you roughly how much of your Claude plan's usage the AI steps will take, split by model, and waits for your yes (or for a later start time, if you'd rather it ran overnight);
  3. shows the areas (rows) it proposes, for you to accept, redo, or edit (and, if rules from files that aren't agent instructions, like a plan or a runbook, would crowd every session, offers to file those with the notes instead);
  4. builds the cube in context-cube/, and proves every line of your original files landed in it, word for word;
  5. archives your original files (they move, unchanged, into a folder your agent doesn't read, since their content now lives in the cube; one command puts any back), asks before rewriting any of your rules, and finishes with a short summary of what happens from now on.

If your plan hits a usage limit partway, run the same command again after it resets; the build picks up where it stopped. Keep working in the meantime: new entries added to a file since the build read it (a new history section, say) are brought in when it continues; any other change to a file leaves that file as the build read it, and out of the archive. Run it again later on a project that already has a cube, and it offers to update it instead of rebuilding.

How much usage it takes, and running it overnight

Before it spends anything beyond a small first look at your files, setup shows its estimate by model, since a token of Haiku uses up a plan's limits more slowly than a token of Opus:

The AI steps will use roughly 1,800,000 tokens of your plan's usage (an estimate). By model:
  Haiku (smallest)   ~1,100,000  history summaries
  Sonnet (mid-size)    ~650,000  recipe, invariant labels, other overviews
  Opus (largest)        ~64,000  row structure

That's a large project: 20 files with 7,600 lines of history and 2,150 of invariants. Most of it goes to Haiku and Sonnet; on the default preset only the row proposal uses Opus, and --preset economy uses no Opus at all. The estimate is calibrated on a real build like that one, where it came within about 10% of each step's actual use. Much of the cost is fixed per AI call (several thousand tokens each, whatever the text), so a small project costs relatively more per line than a big one.

If that's more than you want to spend now, answer later and give a time, such as just after your usage resets (/usage in Claude Code shows when). The steps before your row review run right away, since you review the rows; everything after them, which is most of the usage, starts on its own at that time. You can also pass the time up front: npx context-cube --at 23:30 (or cube build --at 11:30pm).

  • The terminal waits until then, so leave it open and leave the computer on and plugged in, with the lid open: nothing runs while the computer sleeps. On a Mac, it's kept from going to sleep on its own while it waits and works.
  • A question that comes up while you're away gets its default answer, printed in the terminal. The spot check at the end waits for you.
  • If your plan hits its limit overnight, it waits for the reset and keeps going, but starts nothing new more than 8 hours after the time you picked. If the computer slept through the start time and wakes more than an hour late, it asks before starting.
  • Ctrl+C cancels. The build keeps its place, so running the command again finishes it (now, or with --at to wait again).

Nothing is added to your system's scheduler; the waiting is done by the command itself.

Without a terminal (the Claude desktop app)

In a Claude desktop app session, ask Claude to set up Context Cube in the project ("run npx github:Spobi/context-cube here"). Claude runs it, and it uses the app's own copy of Claude Code, so nothing else needs installing besides Node. With no terminal to ask in, setup works one question at a time: each time it needs your say (spending usage, the files to use, the proposed rows, first rules it drafted, the spot check, rewriting your rules), it stops and prints the question, Claude asks you with Claude Code's question box (the one that pops up with answers to pick, and "Other" to type your own), and runs it again with your answer (--answer <question>=<answer>). Nothing is spent before you say yes, and every step already done is kept. Questions that don't need you get their defaults, printed as they go.

The long part of the build runs in the background, so it keeps going when Claude's command ends. Claude checks on it with node context-cube/.tool/cube.mjs build-status, which shows how far it is and any question waiting for you; build-status --stop stops it, keeping its place. Leave the computer on and plugged in while it runs. Picking a later start ("later", then a time) works the same way: the background part waits until then.

You can also run setup yourself in the desktop app's terminal pane (the Views menu, or Ctrl+), exactly as in a terminal. Once the cube is built, desktop sessions use it like terminal ones: the app reads the same CLAUDE.mdand.claude/` settings, hooks included. On a Mac, the app finds Node through the PATH your shell profile sets.

A new project with no memory files yet gets an empty cube (rules, history, invariants) and a few questions to write its first rules. A project with code and git history but no memory files gets its history built from its commits and a set of candidate invariants, drafted from reverted and fix commits and code comments, for you to approve.

What it makes

context-cube/
  CUBE.md                     how to read the cube, and the list of rows
  Y00-rules/                  instructions that always apply
  Y01-history/                what changed and why, oldest first (listed newest first)
  Y02-invariants/             rules that must never be broken
  Y03-…/                      your features, systems, and catalogs
    ROW.md                    the row index: one short entry per box
    X001-some-box/
      Z0-overview.md          what it is, and when to read it
      Z1-invariants.md        rules that hold for it
      Z2-code.md              the code it's about
      Z3-history.md           history entries that touched it
      Z4-detail.md            the full text

Every row (Y) holds boxes (X), and every box has the same five drawers (Z). Ids like Y02.X007 never change or get reused. Your agent's instruction file (CLAUDE.md, or AGENTS.md for other agents) gets a short block with the rules and the list of rows; nothing else in that file is touched.

The whole format is in docs/FORMAT.md, so any tool can read or write a cube.

Day to day

  • Reading: every session starts with the rules and the row list. The agent opens rows and boxes as its task needs them. When it opens a file that invariants govern, a rule file loads and tells it which invariants to read first.
  • Invariants read before an edit: a rule file is only a reminder, and a central file can load a dozen of them at once, so the guard also checks at the edit. An edit near code an invariant is about (a line naming its code, or inside a function or type it names) is held back until the agent has opened that invariant in this session, with a list of what to read; after the context is compacted, it reads them again. See "Reading invariants before editing" below.
  • Routing without guesswork: node context-cube/.tool/cube.mjs related <file or code name> lists, with no AI, the invariants to read before editing it, the boxes about it, and the history that touched it, each with how it was found (the code name it matched, the commit that changed the file, or the box it was reached through), most clearly linked first. Code search skips comments, URLs, and imports, and a plain word (band, head) counts only where the code uses it as code, so prose doesn't tie a box to a file; anything linked only by a plain word or two is listed apart. find <words> searches the cube's text. The cube's own bookkeeping is kept out of ordinary code searches.
  • A ceiling on what loads every session: the block in CLAUDE.md has a size limit (about 3,000 tokens by default). As the cube grows, the row list gets shorter, and cube check suggests rules that are only about certain files so they can load with those files instead (cube edit <rule id> --paths "src/ui/**"), and names rules that came from files that aren't agent instructions, which are often plans or procedures (cube move <id> <row> files one with the row it's about). When an agent opens a file, a one-line rule loads for each invariant that governs it. The ceiling holds: nothing is made a rule that loads every session without asking, and cube new-box won't add a rule that goes over it (a person can raise it).
  • Updating: after each commit, the agent is told which boxes are linked to what changed. It writes a short note, and a helper on a cheaper model files it in the open history entry and adds what changed, dated, to the boxes it made out of date, without rewriting what's there. You can also run /cube-update in Claude Code.
  • Staleness: node context-cube/.tool/cube.mjs status finds boxes whose code changed near what they mention, or whose code names no longer exist, without using any AI. It only reports; --mark writes the findings into the boxes. A short notice at the start of each session lists those linked to recent work. Stale means "check this against the code," never "delete it": the text stays until someone decides it's wrong, and an invariant stays in force.
  • Past and present: history entries are marked as past records. Where an old entry disagrees with an invariant or the current code, the agent is told the invariant and the code win. Notes moved in from plans, reviews, and handoffs are treated the same way: the row index marks a box from a file named like one as "dated", and the agent is told that history after it and the code say what shipped. When a later decision replaced what a note says, cube supersede <id> --by <history entry> --note "<what's true now>" marks it: the text stays, a dated note says what's current, and the box stops pointing agents at invariants. Agents are told to do this when they find one.
  • Summaries checked against their text: cube check points out a number in an AI-written summary that the box's own text doesn't have, since that's how a misread shows.
  • Stats: node context-cube/.tool/cube.mjs stats puts quality first: possible misses (code edited before the invariants that govern it were opened) and boxes opened but possibly unused (nothing they name came up again, a sign their read-when line is too broad). Then it compares what the agent read with what reading the same areas in full would have taken, as a conservative estimate and an upper bound.

Inside a project, the agent runs the cube's commands with node context-cube/.tool/cube.mjs <command>; --help lists them. The tool copies itself into context-cube/.tool/ so hooks and teammates need only Node.

Your original files

Once the cube holds a file's text word for word, setup archives the original, so your agent doesn't read the same things twice. It doesn't ask, since nothing is lost and one command puts any file back; it tells you where the files went. Each original moves, unchanged, into context-cube/.state/archive/, and a short placeholder takes its place saying where the content went. Your agent is kept out of the archive: code search skips it, and in Claude Code reading it is denied. For CLAUDE.md or AGENTS.md, the placeholder is a short pointer, and the cube's always-loaded block stays in the file.

  • Get a file back: node context-cube/.tool/cube.mjs restore HISTORY.md puts the original back exactly as it was (--all for every file). To look at an original without putting it back, restore HISTORY.md --to ~/Desktop/originals copies it there. Claude Code asks you before running a restore.
  • Archive again: node context-cube/.tool/cube.mjs archive archives every original the cube was built from that isn't archived (for example, one you restored). It refuses a file whose current text the cube doesn't hold, so nothing can be hidden by accident.
  • Text added to an archived file (say, a teammate on an older branch added to HISTORY.md) isn't in the cube; cube check points it out, and restore won't overwrite it.
  • Rebuilding from scratch: run uninstall, then restore --all, then move context-cube/ out of the way and run npx context-cube again. Don't delete context-cube/ without restoring first: the archived originals live inside it.

A new project with no memory files has nothing to archive.

Old text stays as written

The text moved in from your files, and every closed history entry, is kept as it was written. The odd old details are the point: "we tried this a year ago and it failed because of X" is what a rewrite or a summary would shorten to "the previous approach failed." So agents never rewrite that text. When it's out of date, they add a dated note below it (cube write <id> Z4 --append) that says what's true now, and keep the box's one-line summary current, since that's what agents read first. Direct edits to its files are blocked.

A person can still change it on purpose. cube replace <id> <drawer> @<file> --reason "..." replaces the text (for example, to fold a pile of notes into one clean version), and cube delete <id> --reason "..." removes a box that holds it. Both ask you to confirm in Claude Code, both go in .state/approvals.log, and the text they take out is kept in .state/archive/.records/, where Claude doesn't read it but you can copy it back. cube check points out any of this text that changed some other way, including a file that went missing, and says where the earlier text can come from: your archived originals, or git if it was committed. If you edited it yourself and meant to, cube replace <id> <drawer> --reason "..." with no text records that.

Invariants need a person's approval

Invariant text can't be edited directly: the agent proposes a change (propose edit, propose delete, propose new), and a person approves it (approve) or rejects it (reject). In Claude Code, the agent asks you as soon as it proposes one, in the question box that pops up: Approve, Reject, or Decide later, with the proposed text beside the choices. Approving then runs approve, and Claude Code asks you to confirm that command; that confirmation is the approval, since it's the step the agent can't answer for you. A change left for later is offered once a session, at a break in the work. Changes that weaken or remove a rule are flagged. A proposed new invariant (including the candidates a build drafts from git history) is visible to agents but labeled as a candidate, and nothing enforces it until a person approves it, so a wrong guess can't quietly become a rule. Every decision goes into .state/approvals.log with who, when, and why. Three layers enforce this: a hook that blocks direct edits and names the command to use instead, a git pre-commit check that catches edits made any other way, and cube check.

To turn approvals off, ask your agent to; it runs cube config set invariants.approval auto, and Claude Code asks you to confirm.

To also require a GitHub review for invariant changes, add a CODEOWNERS file and turn on "Require review from Code Owners" in your branch protection settings:

# .github/CODEOWNERS
/context-cube/Y02-invariants/  @your-github-user
/context-cube/.state/approvals.log  @your-github-user

Reading invariants before editing

When the agent opens a file, a one-line rule loads for each invariant that governs it, but a reminder can be skipped: on a central file a dozen load at once. So the guard hook checks each edit (Claude Code's edit tools, Codex's patches). If the edit is near code an invariant is about, meaning a changed line or the lines around it name that code, or the edit is inside a function or type it names, the invariant must have been opened in this session. If it hasn't been, the edit is held back with the invariants to read, where they are, and about how many tokens they come to. The agent reads them and makes the edit again, with no one having to step in. A write that replaces a whole file needs every invariant that governs the file. Invariants read before the context was compacted have to be read again.

For code where every rule matters on every change, have the check ask for all of them: cube config set invariants.readAllFor "ios/Calling/**,ios/Tests/Call*" (globs from the project root). Then every invariant that governs a file there is read before its first edit, whatever part of the file changes. invariants.readFirst sets the check for everything else: near (the default), all, or off; with off, it still covers the readAllFor files.

One invariant holds edits back at most twice a session. After that the edit goes ahead and cube stats counts it as a possible miss, so a read the hooks couldn't see never stops the work. Edits made through shell commands (a script that writes the file) aren't checked. The check starts once the project's hooks are updated (run setup again), since the guard needs to see what the agent reads.

Teams

A teammate who pulls the project gets the cube working without running setup (a Codex user trusts the project's .codex/ folder once, with /hooks). The cube's hooks go in the shared, committed .claude/settings.json (run setup with --personal to keep them in your own .claude/settings.local.json instead; the read logger always stays personal). At the first session in a clone, the session hook registers what git can't carry in a commit: the merge drivers, the pre-commit check for invariant text, and renumbering after merges. A hooks folder the project tracks itself (husky, say) is left alone. Running setup again on a cube whose hooks are personal offers to share them.

Commit context-cube/ like any other folder (its .logs/ stays on each person's machine); cube check warns while it isn't committed, since until then the cube and any originals archived in it exist only on one machine. Merges are handled for you: generated files never block a merge, history additions go in separate files so two people never edit the same one, each box's bookkeeping merges field by field (so an approval on one branch survives another branch's later changes to the same box), and if two branches both create box Y05.X016, the newer one is renumbered after the merge and every link to it is rewritten. context-cube/.tool/cube.mjs is the program your hooks run, so review a change to it like any code change; it should only change when someone updates Context Cube. GitHub isn't required; a local git repo works, and without git the cube still works as plain files.

Codex

Codex reads the cube too. Setup includes it when it runs in a Codex session, when the project already has a .codex/ folder, or when Codex is on the machine and you say yes; to add it to an existing cube, run node context-cube/.tool/cube.mjs install --agent codex (and uninstall --agent codex takes it out again). A team can mix the two: each agent gets its own files, and both read the same cube.

  • Reading: the always-loaded block goes in AGENTS.md, which Codex reads at the start of every session.
  • Hooks (.codex/hooks.json): the same guard, session notice, and update requests as in Claude Code. Codex edits files with patches, and the guard reads which files a patch changes, so invariant text and the cube's bookkeeping are protected the same way.
  • Invariants that govern a file: Codex has no path-scoped rule files, so the guard hook tells the agent which invariants govern a file when it's about to edit it, or after it prints the file through the shell, once per session.
  • Commands that need a person (approve, reject, restore, replace, delete, and changing a setting): Codex's hooks can't ask you, so the cube adds Codex command rules (.codex/rules/context-cube.rules) that make Codex ask before running one. The guard blocks any such command written so the rules might miss it (chained with another command, say), and tells the agent how to run it.
  • Updates: after a commit, the agent is told what to update and hands it to a cube-updater custom agent (.codex/agents/, low reasoning effort). The cube-update skill (.agents/skills/) is the manual trigger, like /cube-update in Claude Code.
  • Trust: Codex runs a project's hooks and command rules only after each person trusts its .codex/ folder. In Codex, run /hooks once in the project. Until then Codex still reads the cube from AGENTS.md, without the guard or update requests.
  • Not yet: building a cube from existing files needs Claude Code (the command-line tool or the desktop app), whose models run the build's AI steps. The read logger and cube stats cover Claude Code sessions only. Codex reads only the first 32 KB of AGENTS.md by default and the block goes at the end, so cube check warns when a long AGENTS.md pushes it past that.

For other agents, the cube writes an AGENTS.md block and works as plain files, without automatic logging, updating, or enforcement. The core knows nothing about any particular agent; support for another one is a small adapter.

Updating

Run npx context-cube@latest in the project (before it's on npm: npx github:Spobi/context-cube). It updates the project's copy of the tool, its hooks, and its rules, and leaves your cube's content as it is. Then commit context-cube/ so teammates run the same version. The @latest matters: without it, npx may reuse a copy it cached earlier. An older version won't run against a project set up with a newer one; it says so and names the command to use instead. CHANGELOG.md lists what each version changed.

Privacy

Everything stays on your machine: the cube is plain files in your repo, and logs and stats are never sent anywhere. The only network use is your agent's own AI calls during the build and updates. Context Cube doesn't check for new versions over the network; see Updating.

Results

The A/B experiment (cube bench) runs the same tasks in two copies of a real project, one with its original memory files and one with the cube, and a person (or Opus, with cube bench score --ai) scores the changes blind, including a yes/no for each invariant a task must keep. Besides cost and scores, the report measures retrieval, so it can say why a copy did better or worse: whether the agent read each required invariant before its first edit, how many reads it took to find it, how much memory it read before editing, and how many boxes it opened for nothing. Results will be written up here once it has run.

License

MIT. See LICENSE. Contributions are welcome; see CONTRIBUTING.md.

About

Turn a project's AI memory files into a structured cube that coding agents read top-down: short summaries first, detail only when a task needs it.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages