Your agent remembers what used to be true¶
Particles gives your agent a memory you can inspect and correct: see where a remembered claim came from, what changed, and what replaced it.
An agent that remembers by writing to a notes file keeps the line and loses the rest: where it came from, when it stopped being true, what replaced it.
Connect Claude Code Get started See it work Why Particles?
Watch a README change¶
A team moves its deploys from a shell script to GitHub Actions and edits the README. Below is what a real Particles store recorded, in three steps.
The store reads README.md and keeps a snapshot of it. These are the claims it took from the Deploying section.
## Deploying Deploy to production by running `./deploy.sh` from a clean checkout of `main`. The script builds the container image, pushes it to the registry, and restarts the service on the production host.
- Active
Tally is deployed to production by running
./deploy.shfrom a clean checkout ofmain. - Active
The
./deploy.shscript builds the container image, pushes it to the registry, and restarts the service on the production host.
The README is deposited again. It is the same corpus entry with a new snapshot, and the old snapshot is kept, byte for byte.
## DeployingDeploy to production by running `./deploy.sh` from a clean checkout of `main`.The script builds the container image, pushes it to the registry, and restartsthe service on the production host.Production deploys run through the `deploy` GitHub Actions workflow, whichstarts on every merge to `main`. Do not deploy from your own machine;`deploy.sh` is retired.
Extracting the new snapshot replaces the old claim. The old one is kept, with its source and its dates, and points to what replaced it.
- Current
Tally's production deploys run through the
deployGitHub Actions workflow. - Replaced
Tally is deployed to production by running
./deploy.shfrom a clean checkout ofmain.
Inspect all five records
- Current
Tally's production deploys run through the
deployGitHub Actions workflow. - Replaced
Tally is deployed to production by running
./deploy.shfrom a clean checkout ofmain. - Retired
The
./deploy.shscript builds the container image, pushes it to the registry, and restarts the service on the production host. - New
The
deployGitHub Actions workflow starts on every merge tomain. - New
deploy.shis retired.
Then ask the store how to deploy. It answers from the current claims only: the replaced one stays on record, and is no longer offered.
$ particles query "How do we deploy Tally?" --show-particles
CONF EFF AGE EXTRACTOR CONTENT
----------------------------------------------------------------------------------------------------
0.93 0.65 1d general-extractor Tally's production deploys run through the `deploy` GitHub A
0.88 0.62 1d general-extractor Running `make dev` makes Tally available locally at http://l
0.93 0.65 1d general-extractor Tally is a small web app for splitting shared expenses.
0.93 0.65 1d general-extractor `deploy.sh` is retired.
0.93 0.65 1d general-extractor The `deploy` GitHub Actions workflow starts on every merge t
Tally's production deploys run through the `deploy` GitHub Actions workflow. That workflow starts on every merge to `main`, so merging to `main` is what triggers a production deploy. The old `deploy.sh` script is retired and should no longer be used.
For local use, running `make dev` makes Tally available at http://localhost:3000. That is for local development, not production deployment.
The knowledge base doesn't cover other details, such as manual triggers, approval steps, or rollback procedures. Some of these particles are also uncalibrated, so the answer may be incomplete.
These are the store's records, copied as they are; the demo above is limited to the claims about deploying. The changed line is one the store can match to an earlier claim from the same document. A change stated in a separate document, such as a decision record that never mentions the README, is not caught this way yet: today the old claim and the new one both stay active.
Every command that built the store, with real output
$ particles db init
Database tables created.
$ particles deposit README.md --mutability MUTABLE
entry_id: 4ff05a50-4f5d-400e-98a4-d806aab6aef7
snapshot_id: bbf9e423-018d-4fff-b9a8-a37a598795f6
$ particles extract --all-pending
Extracting 1 pending snapshot(s)…
4ff05a50…/bbf9e423… 4 particles
$ # Edit README.md: the Deploying section now names the GitHub Actions workflow.
$ particles deposit README.md --mutability MUTABLE
entry_id: 4ff05a50-4f5d-400e-98a4-d806aab6aef7
snapshot_id: 1f37d56d-01d6-493f-a062-d1fe575b2bd3
$ particles extract --all-pending
Extracting 1 pending snapshot(s)…
4ff05a50…/1f37d56d… 4 particles (1 duplicate(s) suppressed)
$ particles events list
2026-10-30 20:09 4cc50774… EXTRACT_RUN by cli:extract
2026-10-30 20:09 aa4e86b4… CLAIMS_RETIRED by extract
reason: generation cascade: no current snapshot of the entry states the claim
refs: corpus_entry:4ff05a50…, particle:1b5f283a…, particle:808d4b03…
2026-10-30 20:09 2c28bedd… UPDATE_SUPERSESSION by extract-pipeline
reason: Rung 2.5 (ladder): f1213149 superseded by 61e4292b
refs: particle:61e4292b…, particle:f1213149…
2026-10-30 20:08 c82ebbf8… EXTRACT_RUN by cli:extract
Each extract also printed its cost estimate and token usage, left out
here; the two runs together cost about seven US cents. The README's
other two sections produced claims too. The make dev line was read
again in new wording, so its first reading (808d4b03) retired beside
1b5f283a.
92% of full-history accuracy from 1.3% of the tokens¶
Measured on a stratified 150-question sample of LongMemEval, a long-term conversational-memory benchmark (the full-history run was scored over 148 of the 150). Given the same token budget, session notes answer 70.0% and transcript retrieval 60.0%. With no budget at all, session notes come out ahead. The numbers and their caveats →
What makes it different¶
-
Every claim has a source
A claim names the exact snapshot of the document it came from, so every answer traces back to its evidence, claim by claim.
-
Nothing is overwritten
A replaced claim is superseded and a withdrawn one retracted, never deleted. Ask what the store believes now, or what it believed on any past date.
-
Trust is applied when you read
A claim's stored confidence never changes. Source trust and recency are applied at query time, so a new trust policy rewrites no records.
-
Disagreements stay visible
When two sources conflict, the conflict becomes a record for you to review, and your rulings become a reusable source-trust policy.
In our August 2026 survey of the leading memory systems (Zep/Graphiti, mem0, Letta, Supermemory, Hindsight), none documented all four. See the comparison. The same store works for a person, too, as a sourced, dated second brain.
Take your agent's memory out of its hands¶
One command moves Claude Code's memory out of its notes file and into a Particles store. It needs Python 3.11 or later and a model to read sources with: an Anthropic API key, or any OpenAI-compatible endpoint, local models included. The command creates the store itself.
The same store also connects to Codex, Cursor and other MCP clients.
Each session ends by harvesting what happened into the store, so nothing depends on the agent choosing to save it. Each session starts with a small ranked digest of the store's standing beliefs, contradictions flagged rather than hidden; everything else stays out of the prompt until it is asked for. On first run, it also audits the memory you already have:
Audited 23 memory files → 212 beliefs about 58 subjects.
4 potential contradictions (2 across files, 2 contested at extract time)
11 likely-duplicate belief pairs (unjudged similarity candidates; --judge to verify)
7 probably-stale facts (5 aged past their source's decay horizon, 2 expired)
Also: 3 cited sources never captured · 6 beliefs have no resolvable subject
When your agent gets something wrong, you can see which claim it used, which source that claim came from, and what has replaced it since, and fix it at the source. Claude Code memory →
Where to go next¶
-
Use it
pip install linkedparticles, then run the deposit → extract → query loop against your own sources. The reference implementation lives inparticles-engine-py, the repository to star, watch, and file issues against. -
Read the argument
Why knowledge systems keep failing in the same two ways, what a particle is, and the tradeoff this design accepts on purpose.
-
See it work
One store end to end: sources in, an answer that cites its evidence, and a store asked what it believed in 2000.
-
Read the specification
The whitepaper, the technical specification, the conformance profile, and the machine-readable schemas, independent of any one implementation.