Particles

linkedparticles

[linkedparticles.org](https://linkedparticles.org) · [docs.linkedparticles.org](https://docs.linkedparticles.org) · PyPI · Apache-2.0

Particles is shared memory for humans and AI agents. Each particle is one

claim, plus what you need to judge it: who said it, where, when, and how

confident they were. Facts, opinions, and memories are all claims, recorded

the same way as particles. Particles are not edited or deleted. Particles are

superseded, retracted, or disputed in the open. How much to trust it is a

perspective applied at query time, never baked into the record.

linkedparticles is the Engine of the Particles reference implementation: the package you install to actually run a belief store. Give it documents, pages, chat logs, or an agent's own session notes; get back claim-granularity beliefs, each carrying calibrated confidence, an uncertainty kind, a resolved subject, and provenance back to the exact source bytes. Ask a question and the answer cites the beliefs it was built from. Nothing is ever overwritten, so you can ask the store what it believed a year ago and why it stopped.

When your agent is wrong, you can see exactly why, and fix it at the source.

The Engine is a library first. The HTTP API, the CLI, the read-only MCP server, and the resident daemon are all *surfaces* over it.

Install

pip install linkedparticles

Python 3.11+. linkedparticles-core, the store-free Client layer, is pulled in automatically.

Extraction and the written answers call a language model. The quickstart below uses Anthropic, and any OpenAI-compatible endpoint works too, hosted or local (Ollama, llama.cpp, vLLM): each purpose names its provider in config.yaml (named providers). Deposit, the session digest and structural queries make no model call at all.

Sixty seconds

export ANTHROPIC_API_KEY=sk-ant-...

particles db init

Deposit a source (file, URL, or literal text) into the append-only corpus

particles deposit https://en.wikipedia.org/wiki/Pluto

Extract claim-granularity beliefs with confidence, subjects, and provenance

particles extract --all-pending

Ask in natural language; the answer cites the particles behind it

particles query "Why is Pluto not a planet?"

Health-check the store: contradictions, staleness, orphaned links

particles lint

Because nothing is overwritten, the store can replay its own history. --as-of is the assertion-time lens. It answers *what did the store believe at T, and why did it stop*, not what was true of the world at T:

particles query "How many planets are in the Solar System?" --as-of 2000-01-01

→ the belief as it stood then, and why it no longer stands: SUPERSEDED,

retired 2006-08-24, superseded by "Pluto is a dwarf planet."

There is a clickable version of that belief history on the front door. Step by step: getting started, then as-of time travel.

Wiring it into an agent

particles mcp serve                 # read-only MCP server (stdio), any MCP client

particles init claude-code # session-start digest, session-end harvest particles engine serve # HTTP API, for a shared or remote engine particles export obsidian ./vault # also: anki, wiki, logseq, notion, graph, jsonl

It can also stand in for the reference memory server, and it plugs into LangChain as a retriever and a tool set. See Claude Code memory, swapping in for the reference memory server, and using from LangChain.

Does it hold up?

Measured on LongMemEval, the multi-session agent-memory benchmark, with a full-context oracle and a no-memory floor run as controls in the same harness:

The oracle and floor rows come from a separate control run in the same harness, the day before the three runs the Particles row averages; the benchmarks page names the report of record for each row.

Method, per-question-type breakdowns, comparator memories, and the budget-matched arm (including the arms where Particles *loses*) are on the benchmarks page, with the report JSONs of record beside them.

Security posture

A memory layer is an *input-shaping* attack surface: it does not merely hold data, it shapes what the agent believes and does next, so a poisoned claim is an instruction on a delay timer.

Fifteen adversarial audits have covered this code, and each returned GO-WITH-FIXES. The verdicts are quoted as given.

Not every release in those ranges contains the releases numbered before it: 1.212.0, 1.214.8 and 1.215.0 were tagged before their merge. Every release from 1.215.1 on contains every lower release. Nor does a release number prove its commit passed CI: 1.222.3, 1.222.4 and 1.222.5 were tagged on commits whose CI run failed, and the release tagger now tags a version only after its CI run passes.

Three of the fix rounds changed the design rather than a defect. An engine with no key serves reads only: it refuses every write, from loopback too, and the particles command line, the Claude Code hooks and the MCP servers write the local store in-process and need no key. Each client can hold a key of its own whose role bounds it: a reader key writes nothing, an agent key writes only as its own principal, and PARTICLES_API_KEY and every per-client operator key carry the operator's authority, by design, so give an operator key only to clients you would give that authority. The local refresh trusts a store, its config file or a rule file only when you alone can write it.

A cloned repository cannot configure Particles, or give a stdio MCP server or a Claude Code hook its store, unless a relative path you set points into it (a relative PARTICLES_CONFIG for the command line, a relative DATABASE_URL for an MCP server) or particles init claude-code --store default runs inside it. A store it ships, found by a path relative to the directory, cannot direct a refresh to a file on your disk, and that store's blob directory cannot direct a blob read or write to another file. No HTTP route reads a file the caller names on the engine's disk. A web page cannot send writes to an engine on loopback, or read from one that runs without a key, and