What NeuralMind remembers, and what it forgets
Four questions people ask about NeuralMind’s memory, answered from the code. Each answer says what is built, where the limit really is, and the command that shows it on your machine.
Does NeuralMind remember my preferences?
No. It remembers your code, the decisions recorded about it, and what your last session was doing. It does not keep a profile of you or of how you like to work.
How it works
- The last session’s thread (v4.8.0+). A fresh or cleared Claude Code session, and a Hermes-Agent session through its plugin, starts with a recap of the previous one: its first prompt and its last three, each credential-redacted and cut at 200 characters, and the files it edited. Say “remember this endpoint tomorrow” near the end of a session and tomorrow’s session sees it, labelled as context rather than an instruction. A recap older than 14 days isn’t shown (
NEURALMIND_SESSION_RECAP_MAX_AGE_DAYS). The newest ten session records stay on disk, andneuralmind recap --cleardeletes them. - Decisions about the code.
neuralmind decisions recordstores a decision with its rationale and the files it governs. Withneuralmind init-hook .installed, it goes STALE when a commit changes one of those files, andneuralmind decisions queryfinds it by meaning, not only by shared words. A project convention with a reason behind it belongs here. - Which files go together. The synapse layer learns which files you edit and query together, per project.
Check it yourself
$ neuralmind recap .
$ neuralmind decisions query "why do we hash tokens?"
Will a feature branch pollute the memory main uses?
Mostly not. On any branch other than the default, what NeuralMind learns from your work goes into that branch’s own memory namespace, with no setup. The exception is the call graph: call and import edges a build finds go into the shared baseline every branch reads.
How it works
- On a non-default branch, every association learned from use is written to
branch:<name>. The default branch comes fromorigin/HEAD, ormain/masterwhen there is no remote. A detached HEAD writes topersonal. - Recall reads a weighted merge: the branch you are on at full weight, your
personalmemory at 0.8 and the team’ssharedbaseline at 0.5. On the default branch the active namespace ispersonalitself, so nothing changes until you branch. - The code index follows the checkout too:
neuralmind init-hook .installs a post-checkout hook that rebuilds it after a branch switch (v4.13.0+). - To pin a namespace instead, set
NEURALMIND_NAMESPACE, ormemory_namespaceinneuralmind-backend.yaml.
Check it yourself
$ neuralmind memory inspect .
$ neuralmind memory reset . --namespace branch:feature-x
Read the source
Is NeuralMind tuned for Claude?
Its context isn’t: every agent and every model gets the same plain text. Its integration is: Claude Code gets the most from it, because its hooks deliver that context without the agent having to ask.
How it works
- NeuralMind picks context without a language model: from the code graph, a vector index built by a small local embedding model, and BM25. It returns plain text and Markdown with no model-specific prompt format, so the output is the same whichever model reads it.
- It reaches agents three ways: the MCP server for any MCP client, the CLI (pipe
neuralmind queryinto any model, a local one included), and a Python API. - Size comes from progressive disclosure, not from a per-model setting: a small wake-up context first, then the layers a question needs.
Check it yourself
$ neuralmind wakeup . > CONTEXT.md
$ neuralmind query . "How does auth work?"
Will it forget code I haven’t touched in a while?
Not the code. The index, meaning every symbol, import and call edge and their embeddings, is rebuilt from your source and does not decay. What fades are learned associations, at a rate set by how often you used them.
How it works
- Learned associations decay on a wall-clock half-life: 30 days by default for personal and branch memory, 60 for the team’s shared baseline, 1 day for session scratch.
- Each association learns its own half-life from how often it was reinforced, between 3 and 120 days. Used often, it outlasts the default; used rarely, it fades faster than the default. The longer it sits idle, the closer its rate gets back to the default.
- An association reinforced five or more times gets long-term status: it decays to a floor of 0.20 and is never pruned. Others are pruned below 0.01.
- Call and import edges are seeded into the shared baseline again on every build, so the structure of code you never edit comes back with each rebuild.
| Used | What it learns | Then |
|---|---|---|
| Every day for ten days | A half-life over 60 days | Two idle weeks: above 80% of full weight |
| Once a week, six times | Long-term status (five uses or more) | A year idle: held at the 0.20 floor |
| Three times, a month apart | A half-life under 15 days | Two idle months: still kept; five: pruned |
Check it yourself
$ neuralmind synapse stats .
$ neuralmind memory inspect .
Read the source
Found an answer that doesn’t match the code?
These answers are checked against the source they link. If one has drifted, tell us and we will correct the page or the code, whichever is wrong.