Long-term memory infrastructure GreyMatter v2.2.0macOS
Find what you already decided, learned or tried.
GreyMatter keeps your decisions, methods, mistakes and experience as notes on your own disk, so they can be found again from a later session or another project. It works with Claude Code today, and is built toward a memory that stays yours, whichever model you use.
Stack
- Python
- Bash
- Swift
- WebGL
- GitHub Actions
- Apache 2.0
- v2.2.0
- the current public release, 30 September 2026, open source under the Apache 2.0 licence.
- 54 releases
- published on the public repository.
- Markdown + git
- your notes are plain files on your disk, with their full history.
- 2.4 ms
- per search across 1,000 notes, on a synthetic bench (27 September).
The problem
A new session does not carry forward what the last one learned.
Your rules and files are still there. What was decided, tried and learned along the way is not, unless someone writes it down.
-
Monday
You and your agent work out why the cache breaks, and decide how to fix it. It takes an hour, and the answer is good.
-
Thursday
A new session. You explain the cache and the decision again before you can move on.
-
Next month
Another project hits the same problem. The answer exists, in an old session nobody will reopen, so the work is done twice.
What it is for
Preserve, retrieve, reuse.
Decisions, methods, mistakes, experiences and accumulated knowledge, kept over time. Three goals follow from that: goals, not measured gains.
- PRESERVE then
- RETRIEVE then
- REUSE
-
Less re-contextualization
Not rebuilding the whole context of work you have already done.
-
Less repetition
Not redoing a reasoning, a search, a decision or an exploration that was already carried out.
-
Past experience, when it is relevant
Finding a past experience again when it matters for the work in front of you.
Today · v2.2.0
How it works today
Today, it works with Claude Code.
GreyMatter can turn what is worth retaining from a Claude Code session into linked Markdown notes, versioned with Git on your disk.
Menu bar · in v2.2.0
Watch a note travel from one session to the next.
Two real Claude Code sessions, with the pill above them. What the first session works out is distilled into a note and filed; the second gets it back before Claude answers. Each agent lights up under the pill in its own colour.
Filmed with automatic recall switched on (BRAIN_RECALL_AUTO=1). By default, recall waits until you ask: ?brain, brain recall, or “search my notes”.
-
Distillation at session end
When a session closes, its transcript is archived. If it ran to 20 messages or more, a distiller keeps what is worth retaining: new notes, one fact each, with their source and a confidence level, or updates to existing ones.
-
Recall on request
Type ?brain, brain recall or “search my notes”: two or three relevant notes are pointed to in context. By default, no note is injected unless you ask; a session opens with at most four resume points found in your notes.
-
One memory for every project
Notes live in a shared memory repository, so relevant past memory can be searched again from another project. Links between notes can be followed by hand.
-
Four agents, eight missions
Distil, file, challenge, link, archive, repair, watch the machine, synthesise: four agents share these eight jobs.
-
Freshness review
A note that was never re-checked enters a review queue, dated from the git history.
-
Updates that ask first
Each session checks for a new engine version and your agent asks before installing it. brain update --rollback returns to the previous one.
- 01 Your notes Markdown files versioned with git, in their own folder, apart from the engine.
- 02 On request A lexical search picks two or three relevant notes, from any project, and points the conversation to them.
- 03 During the session Every file read or written is logged.
- 04 Session end The transcript is archived. What is worth retaining is distilled into notes through Claude Code's own command line, filed, then committed to git.
What the project works on
Durability, provenance, retrieval, context selection.
The current work is on four things. Each one says where it stands.
-
Durability
Nothing captured should be lost: not to a crash, an update or an uninstall.
Being hardenedlocal branch, below
-
Provenance
Each new note is meant to say which session it came from, with an excerpt. Older notes are not rewritten, so not all of them do.
Today, for new notes
-
Retrieval
The right notes come back when you ask, from any project.
Todaymeasured below
-
Context selection
What enters the agent’s context, and when. Notes offered on their own were rarely opened, so recall now waits to be asked.
Today on requestthe rest is research
Durability before intelligence
First, nothing gets lost.
A memory that quietly drops a session is worse than none, because you trust it. So the order of the work is fixed, and each step waits for the one before it.
- DURABILITY comes before
- TRUTHFUL STATE comes before
- RETRIEVAL comes before
- INTELLIGENCE comes before
- MAGIC
Today · v2.2.0
Published
- Engine and notes live in separate folders.
- Updates ask before installing. v2.2.0 includes update and rollback mechanisms, while lifecycle hardening remains on an unreleased remediation branch.
- Notes are plain Markdown under git: every change has a history.
In remediation · local branch, not released
Being hardened
- A save is acknowledged only after every declared note has been read back from disk.
- Each acknowledgment leaves a receipt, and writes go through a journal.
- A session that ends while the command line is unavailable is queued and caught up, not dropped.
- One derived state says “unknown” rather than guess.
- Install, update, rollback and uninstall keep every byte of an existing note folder.
OneMemory
One memory, from experience to answer.
The path a piece of work follows, step by step. Each step says how much of it exists today. APPLY is inside TODAY as an observed capability, but it is barely measured. Whether retrieved memory is applied reliably and usefully remains a research question.
- EXPERIENCE You work with your agent.
Today
- CAPTURE The transcript is archived when the session ends.
Today
- SURVIVE The session outlives a crash or a missing command line.
Partly today · hardened in remediation
- UNDERSTAND A distiller writes one fact per note.
Today
- PROVE New notes cite the session they came from; each save will leave a receipt.
Source today · receipts in remediation
- REMEMBER Notes are Markdown under git, on your disk.
Today
- FIND Two or three notes come back when you ask.
Today
- APPLY The agent uses the note in its answer. Measured once, on one repository.
Barely measured
- TODAY ENDS HERE
- CONTINUE The same memory follows you to another agent or model.
Direction
- BEYOND Brain, State, Library, Runtime: the direction below.
Direction
Memory is not enough
Finding a note is not the same as using it.
Each step below can succeed while the next one fails. They are measured separately here, and the ones that are not measured say so.
- STORED is not the same as
- EXPOSED is not the same as
- SELECTED is not the same as
- RETRIEVED is not the same as
- APPLIED is not the same as
- PROVEN USEFUL
- 4.27%
- of the notes offered automatically were opened: 139 of 3,256 over 30 days. Since 9 September, recall waits to be asked.
- 10/10 vs 0/10
- test questions answered with the full system, against none with nothing. One repository, one author, 12 August.
- Tied with BM25
- on LongMemEval (26 September), which measures retrieval only: 96.8% recall@5, the same as plain keyword search.
Direction · not built yet
Direction · beyond Claude Code
Models change. Your continuity shouldn't.
Today, the continuity holds across sessions and projects, with Claude Code. The direction is for it to belong to you rather than to whichever model happens to be running, and to survive a change of agent, model or provider. The diagram says, function by function, how much of that exists.
You
What you know, where you stand and how you work, kept as files on your disk.
Brain
What you know, lived through and decided.
Partly today: the note repository
State
Where you, or a project, stand right now.
Partly today: resume points
Library
How you work: rules, methods, checklists, known failures.
Direction
Runtime
What to put in the current agent's context, and when.
Partly today: recall in Claude Code
Legacy
What you choose to pass on, curated by hand. Preservation, not simulation: nothing speaks in your name.
Concept only
Agents that read from it
- Claude Code
Today
- Other CLI agents
On request today
- Tomorrow's model
Direction
The model is not the memory.
Models improve and get replaced, and that is good news. The continuity belongs to the user, not to whichever model happens to be running: what you worked out with one of them should not have to be relearned by the next.
GreyMatter keeps that part outside any model, as plain files you can read, move and delete.
Research · hypothesis
Open questions
What is not known yet.
Each hypothesis comes with the test that would settle it. None of them is a claim.
-
Continuity speeds up development
A personal impression, not a measurement. It is not claimed here.
Test: the same tasks, with and without, several people
-
Retrieved notes are applied reliably and usefully
One A/B scenario so far, on 30 September.
Test: many scenarios, scored blind
-
Continuity across agents
Other CLI agents can search the notes on request, without the automatic capture loop.
Test: one project, two agents, the same questions
-
Consolidation
Merging notes that say the same thing, without losing their sources.
Test: answer quality before and after merging
-
Adaptive forgetting
Letting stale notes fade instead of piling up.
Test: fewer notes, the same answers
Current reality
What it does, and what it does not.
Today · v2.2.0
Does
- Turns what is worth retaining from a Claude Code session into linked Markdown notes, under git, on your disk.
- Finds two or three relevant notes when you ask, from any project.
- Keeps the engine apart from your notes; updates ask first. Update and rollback exist in v2.2.0; lifecycle hardening remains on an unreleased remediation branch.
- Runs on macOS, with a menu bar pill and a map app.
Today · limits of v2.2.0
Does not
- Run on Linux or Windows yet: four places still assume macOS.
- Keep your sessions away from your model provider: they are processed there, including the automatic end-of-session distillation.
- Make your agent faster or smarter: that is not claimed.
- Simulate you, or speak in your name.
Research · hypothesis
Being researched
- Whether retrieved notes are applied reliably and usefully.
- Continuity across agents and models.
- Consolidation and adaptive forgetting.
Install in two commands.
GreyMatter installs as a Claude Code plugin. Every session checks for a new version and asks before installing it.
/plugin marketplace add Yuno15-bb/GreyMatter-engine
/plugin install greymatter@greymatterPublic version: v2.2.0, 30 September 2026, macOS. The durability work marked “in remediation” lives on a local branch and is not released yet.
Questions
Frequently asked.
Is this memory for Claude Code?
Yes, today. GreyMatter is built on Claude Code hooks: it distils when a session ends and recalls when you ask. That is the part that ships.
Does it work with other agents?
On request: other CLI agents can search the same notes, but without the automatic capture loop. Continuity across agents is a direction, not a finished feature.
Is everything local?
Your notes are stored locally, as Markdown under git. Your sessions are not: like any Claude Code session, they are processed by your model provider, and that includes the automatic distillation that runs when a session ends. GreyMatter does not create a GreyMatter account or a hosted copy of your memory.
What goes over the network?
A git fetch of the published versions, to check for updates; the end-of-session distillation, which goes through Claude Code's command line and so reaches your provider; the map app, whose code loads its 3D library from a public CDN; and, only after maintenance was stopped by the usage limit, a one-word request to Anthropic, sent with your Claude Code login, to see whether it can resume.
How does it compare with Mem0, Zep or claude-mem?
They tackle related problems, often with more reach. On the one public retrieval benchmark run here (LongMemEval, 26 September), GreyMatter tied plain BM25 keyword search and scored close to claude-mem's search; claude-mem's full memory, Mem0 and Zep were not tested. No superiority is claimed.
Will it make my agent faster or smarter?
That is not claimed. It gives your agent notes it would not otherwise have. Whether that saves time is an open question, listed under research above.
Who does the memory belong to?
To you. Notes are files on your disk, in a git repository you control, readable without GreyMatter. Today that continuity holds across sessions and projects with Claude Code. Making it belong to the user rather than to whichever model is running, across agents and providers, is the direction.
How do I uninstall it?
Follow the install guide. Uninstalling is meant to remove the engine and leave your notes folder alone, but that has not been demonstrated on v2.2.0. Until the durability work ships, keep a copy of your notes folder first: it is a plain git repository.
Install and uninstall guide ↗- Role
- Design, architecture, extraction, publication
- Context
- Personal project · open source · 2026
- Result
- 54 releases under Apache 2.0; v2.2.0 published on 30 September 2026. The durability work marked “in remediation” lives on a local branch and is not released yet.