Skip to content
MCP server

Particles

Append-only ledger of sourced, dated, confidence-scored claims that agents cite

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted, API
Runs
Locally
Version
1.224.6
Listing updated
3 days ago

About Particles

Particles is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.

Each record, a particle, is one claim plus what is needed to judge it: who said it, where, when and how confident they were. Particles are never edited or deleted; they are superseded, retracted or disputed in the open, and how much to trust one is decided at query time. Because nothing is overwritten, you can ask what the store believed at a past date and why it stopped, using an --as-of lens, and every answer cites the beliefs behind it.

The MCP server is the read-only surface over the Python engine. Store-reading accessors work without a model key, while query composes a cited answer and the semantic half of lint reasons over claim pairs, and both need an Anthropic key. Write tools are switched on only for stores named in the mcp.write.enabled_stores allowlist. The README says any OpenAI-compatible endpoint, hosted or local, also works for extraction and answers.

A single command, particles init claude-code, adds session-start and session-end hooks for Claude Code memory. The engine is Apache-2.0 and installs with pip install linkedparticles on Python 3.11 or newer.

Install

Run in a terminal

claude mcp add particles --env ANTHROPIC_API_KEY='<ANTHROPIC_API_KEY>' -- uvx linkedparticles

Add to claude_desktop_config.json

{
  "mcpServers": {
    "particles": {
      "command": "uvx",
      "args": [
        "linkedparticles"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "particles": {
      "command": "uvx",
      "args": [
        "linkedparticles"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "particles": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "linkedparticles"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "particles": {
      "command": "uvx",
      "args": [
        "linkedparticles"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "particles": {
      "command": "uvx",
      "args": [
        "linkedparticles"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}

Configuration

  • ANTHROPIC_API_KEYAnthropic API key. Required for the tools that call a model — `query` composes a cited natural-language answer, and the semantic half of `lint` reasons over claim pairs. The accessors that only read the store (`particle_show`, `particles_list`, `subjects_*`, `events_*`, `graph_view`, `quality_report`) work without it.Required
  • DATABASE_URLSQLAlchemy URL of the belief store to serve, used as given, so write a SQLite path absolute: a relative one opens against the directory the server starts in. Without it, and without PARTICLES_CONFIG, the server serves the store `~/.particles/config.yaml` names (a relative path there is read under `~/.particles/`), or `~/.particles/particles.db` when that file names none, never a store in the directory it starts in.
  • PARTICLES_CONFIGPath to the config file holding the rest of the server's settings: additional stores, model selection per purpose, and the `mcp.write.enabled_stores` allowlist that turns the write tools on. This is the supported way to give the server settings. Without it the server reads `~/.particles/config.yaml`, never a `config.yaml` in the directory it starts in. Give it as an absolute path: a relative one is refused. When you set it, also set `DATABASE_URL` to an absolute path or name one as `storage.database_url` in the file: a server started with a config file refuses a store path relative to its working directory, and refuses to start while any store under `storage.stores` has one.

Tools this server provides (6)

Taken from the project documentation; the running server may differ.

query
Composes a cited natural-language answer from stored particles.
lint
Checks the store for contradictions, staleness and orphaned links.
particle_show
Shows one particle.
particles_list
Lists particles.
graph_view
Returns a graph view of the store.
quality_report
Reports on store quality.

What it does

Append-only claims
Claims are superseded or disputed in the open, never overwritten.
Cited answers
Query answers cite the particles they were built from.
As-of history
Ask what the store believed on a past date and why it changed.
Store health checks
Lint finds contradictions, staleness and orphaned links.
Claude Code memory
One command installs session digest and harvest hooks.
Write allowlist
Write tools stay off unless a store is explicitly enabled.

Good for

  • Give a coding agent a durable, auditable memory
  • Trace a wrong agent answer back to its source claim
  • Ask what a knowledge base believed a year ago
  • Export beliefs to Obsidian, Anki, Logseq or Notion
  • Find contradictions across ingested documents

Pricing

Open source

Apache-2.0; model calls use your own API key

Prices change. Check docs.linkedparticles.org before you buy.

Particles FAQ

Is the MCP server read-only?

By default yes; write tools turn on only for stores listed in the `mcp.write.enabled_stores` allowlist.

Do I need a model API key?

Only for tools that call a model, such as `query` and semantic `lint`; read-only accessors work without it.

What licence does it use?

Apache-2.0.

Can it use a local model?

The README says any OpenAI-compatible endpoint works, including Ollama, llama.cpp and vLLM.

Is Particles free?

Yes. Particles is open source, so you can use and self-host it for free.

How do I add Particles to Claude Code?

Run this command in your terminal: claude mcp add particles --env ANTHROPIC_API_KEY='<ANTHROPIC_API_KEY>' -- uvx linkedparticles

What are the best alternatives to Particles?

The closest alternatives to Particles are Codebase Memory, XERJ, Claude Code Ultimate Guide, Nautilus Compass Memory and note1.

Alternatives to Particles

  1. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  2. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  3. MCP server for searching the Claude Code Ultimate Guide from any MCP client

    Runs locally
    • Open source
    • 6.5K GitHub stars
    • AI models and LLM tooling
  4. Local-first long-term memory layer for AI agents, served over MCP

    Not checked yet
    • 5 tools
    • Remote
    • Open source
    • 1.3K GitHub stars
    • Knowledge and memory
  5. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity