silica-agent 0.4.1

Every other tool reads your notes.
Silica is the one that answers for them.

Point it at a folder of docs or at a codebase. It grows the vault, links it, dedups it,
audits it, and answers from it. Every write it makes is re-read afterwards, and reverted if it
broke something. Local-first. Your files stay plain markdown, readable with or without it.

78% answerable accuracy and ~90% correct refusals on LoCoMo  ·  100% write integrity across a real 758-note vault
_{how these were measured}

Why Silica

The problem

Two things go wrong the moment you give an assistant access to what you know.

1. It answers from somewhere other than your material. The model's own memory, a plausible paraphrase, a note that stopped being true a year ago. The answer reads the same either way, so you cannot tell which one you got.

2. It edits your material and nobody checks the edit. A merge orphans a note, a rewrite breaks a link, a cleanup flattens a distinction you cared about. Nothing fails loudly. You find out three weeks later, if at all.

• And it never has to live with the mess. A vault decays on its own: the same idea captured five times, notes nothing points at any more, links to a file that moved, a subsystem documented against a commit from three months ago. An assistant that only reads has no stake in any of that.

The usual remedy makes all three worse: the tool copies your notes into a store of its own. Now the thing being answered from is not the thing on your disk, and you cannot open it to check.

Silica takes the opposite position. The vault is the product, not the transcript. Your folder of markdown is the database, Silica is answerable for the state it is in, and every write it makes passes a gate that re-reads what it just wrote. It runs on your machine: local models (LM Studio, Ollama) are first-class, and giving an endpoint its start command once (SILICA_EMBEDDING_SERVE_CMD, SILICA_RERANK_SERVE_CMD, SILICA_PROVIDER_SERVE_CMD) is enough for Silica to bring that server up itself whenever it finds it down.

_{New to this? A "vault" is just a folder of markdown (.md) files. If you already use Obsidian, that folder is your Obsidian vault, and Silica works on it directly.}

Compared to the alternatives

Everyone else either only reads your material, or owns a copy of it you cannot read. Silica is the one that treats your own file tree as the database, and puts a compiler-style gate in front of every change to it.

The two nearest neighbors are worth naming. Basic Memory is the substrate twin: markdown on your disk, wikilinks, MCP, same AGPL license. LLM Wiki is the closest in ambition: a desktop app that compiles your documents into a wiki and keeps it current.

The rest of the field. Memory agents (Mem0, Zep, Letta, Cognee, Supermemory) ingest your material into a store of their own; Letta is the only one with rollback, and none of them verifies a write after it lands. Repo wiki agents (DeepWiki, OpenWiki, GitNexus, Graphify) read a codebase and emit an artifact next to it: good maps, read-only by design, and they never curate a human's notes. Graph frameworks (GraphRAG, LightRAG, HippoRAG, Graphiti) build an index, not a folder you can still open in a text editor.

What only Silica does

• Verify or revert on the memory substrate itself. 2026 produced an entire memory-poisoning literature proposing exactly this loop, stage the write, validate it, commit or roll back: Cordon, MOSS, MemLineage, MemAudit, SMSR. Every one of them is a research prototype. Silica ships the loop: one FSM entry point, a post-write re-read, an automatic revert on mismatch, /undo and /revert behind that. Read the scope of the claim before leaning on it.
• A core that survives with no models at all. The co-occurrence concept graph, the BM25 leg, and MinHash dedup need no embedder. Competitor cores are LLM-mandatory by construction, and the incentive runs that way: their business is the model call.
• Notes and code as one substrate, behind one gate. The split in the field is clean and nobody crosses it. Memory agents never touch a codebase; wiki agents never curate a human's notes.
• Graph-safe mutation of links a human wrote. Obsidian redirects links but has no agent driving it. Agents have no human link graph to keep intact. Silica has both.
• Abstention as a published number. Mem0's own 2026 benchmark write-up concedes the market underreports it. Silica prints correct refusals next to accuracy, and ships the unflattering rows unedited.

What Silica did not invent

Credit where it is owed. Plain markdown, local-first, AGPL is the entry ticket to this category and Basic Memory got there too; Silica pays it in full, with no tier above the local one. A graph with community detection and an interactive view ships in Graphify, GitNexus, LLM Wiki, and GraphRAG; what Silica adds is that the same co-occurrence structure is also a retrieval leg. Self-linking atomic notes are A-MEM's thesis, and old news in Obsidian plugins; Silica's part is that those links survive a merge, a split, and a rename. Staleness against the code is Fiberplane Drift's reformat-immune AST fingerprint, Swimm sells it, OpenWiki schedules it; Silica runs it inside the vault that also holds your notes, and /impact, from a diff back to the notes it invalidates, is the piece almost nobody replicates. Typed relations are Graphiti's, with per-edge validity intervals Silica does not model, computed here on demand rather than frozen at ingest. An MCP server and local models are table stakes: four drivers, one gate, no privileged client.

Install

Reading a vault needs no model and no API key, so the shortest way in is to hand your folder of notes to an agent you already run and ask it something:

silica setup claude             # or: setup codex, setup opencode

That writes the MCP server into your client's own config, and your assistant can search, recall, and read your notes from the next session on. Nothing else is configured, nothing is asked.

Writing notes needs a model. That is what the wizard is for:

uv tool install silica-agent    # or: pipx install silica-agent
silica init                     # interactive setup: vault, model, embeddings
silica                          # start the interactive session

If a provider key is already exported in your shell (OPENROUTER_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, MISTRAL_API_KEY, XAI_API_KEY), Silica picks a model for it and silica init stops asking which one.

silica curates the folder you launch it in (the repository root, when that folder is inside one). Your settings live in ~/.silica/.env and follow you between folders; a .env in the project overrides them there.

Make a read-only audit your first move. It writes nothing, and it shows you the hubs, bridges, and orphans already sitting in your vault:

/report

uv tool install 'silica-agent[gui]'      # web GUI: silica --gui
uv tool install 'silica-agent[mcp]'      # MCP server: silica mcp
uv tool install 'silica-agent[connect]'  # Obsidian plugin bridge: silica connect
uv tool install 'silica-agent[pdf]'      # PDF nucleation
uv tool install 'silica-agent[rerank]'   # in-process cross-encoder rerank
uv tool install 'silica-agent[all]'      # everything above except dev

git clone https://github.com/kiycoh/silica-agent.git
cd silica-agent
uv pip install -e '.[dev]'

Four ways in

One vault model, four drivers. What changes is who holds the write key.

flowchart LR
    T["Terminal<br/>silica"] --> FSM
    G["Web GUI<br/>silica --gui"] --> FSM
    O["Obsidian plugin<br/>silica connect"] --> FSM
    M["Any MCP client<br/>silica mcp"] --> FSM
    FSM["Injector FSM<br/>the single write path<br/>verify or revert"] --> V["Your folder of<br/>plain .md files"]

    style FSM fill:none,stroke:#3987e5,stroke-width:2px
    style V fill:none,stroke:#3987e5,stroke-width:2px

_{Four front doors, one gate. Switching driver changes the interface, never the rules a write has to pass.}

1. Web GUI  ·  silica --gui

A chat-first interface at http://localhost:8765. Query and curate from the browser, watch answers stream in, open the graph. Start here if you are new.

2. Terminal  ·  silica

The interactive REPL. Every command in the reference lives here, and it is the fastest driver once you know the verbs.

3. Obsidian plugin  ·  silica connect

A live bridge into the Obsidian desktop app: Silica reads and writes the vault you already have open, with rollback and cache behind every change, and every write shows up in a changes panel with a per-file diff. The plugin side lives in kiycoh/obsidian-silica.

4. Agent memory  ·  silica mcp

Silica serves your vault over stdio to any MCP client, so an assistant recalls your real notes and real decisions before it answers. One command line, uvx --from 'silica-agent[mcp]' silica mcp, and no model or API key on the read path: search, recall, and note reading run on the vault alone.

silica setup <client> writes that line into the client's config for you, with the resolved vault path filled in:

silica setup claude      # delegates to `claude mcp add`
silica setup codex       # ~/.codex/config.toml
silica setup opencode    # ~/.config/opencode/opencode.json

It backs the file up before touching it, leaves an existing silica entry alone, and takes --dry-run to print the block instead, or --config <path> for a project-local file.

Claude Code. This repo is also a plugin, so the server and the recall/capture skill arrive together:

claude plugin marketplace add kiycoh/silica-agent
claude plugin install silica@silica

[mcp_servers.silica]
command = "uvx"
args = ["--from", "silica-agent[mcp]", "silica", "mcp"]

[mcp_servers.silica.env]
SILICA_VAULT = "/path/to/your/vault"

{
  "mcp": {
    "silica": {
      "type": "local",
      "command": ["uvx", "--from", "silica-agent[mcp]", "silica", "mcp"],
      "enabled": true,
      "environment": { "SILICA_VAULT": "/path/to/your/vault" }
    }
  }
}

What you can do

Clear an inbox without losing anything.
Drop raw clippings, drafts, PDFs, or Jupyter Notebooks (.ipynb) in a folder. /nucleate Inbox/* distills each one into an atomic note, checks it against what you already have so you do not end up with a fifth copy of the same idea, and files it. Hand it twenty files at once and each one still goes through the same gate.

Ask your notes instead of your memory.
/explain "<concept>", /compare "A" "B", /summarize <folder>, /quiz [note]. All read-only, all grounded in the vault. Graded answers are logged, so untargeted /quiz draws from the notes you have missed before: what you did not know comes back, what you already knew does not.

When the vault does not have it.
If every search a turn ran came back empty, Silica says so instead of answering thin, and names /web. Typing it is the consent: the answer comes from the web, with citations appended from the pages that were actually opened rather than from what the model claims it read. Fetching is direct, with no third-party reader in the path. That turn writes nothing; /keep saves it to the inbox when it was worth keeping, and /web-search "<topic>" does the same in bulk for a whole question.

Reorganizing by intent, typed relation maps, reading paths, diagrams, contested claims, dedup, and the rest are in the command reference.

How an answer is grounded

A question is not handed to one index and hoped for. It runs down independent legs, and the results are fused by rank:

flowchart LR
    Q["Your question"] --> E["Embeddings<br/>semantic similarity<br/>needs an embedding model"]
    Q --> C["Co-occurrence<br/>concept graph<br/>no model needed"]
    Q -. "opt-in" .-> L["Lexical<br/>BM25 + fuzzy<br/>no model needed"]
    E --> F["RRF fusion<br/>combines by rank, not by score"]
    C --> F
    L -.-> F
    F --> R["Ranked notes, each carrying<br/>which leg found it"]

    style C fill:none,stroke:#3987e5,stroke-width:2px
    style L fill:none,stroke:#3987e5,stroke-width:2px

Fusing by rank is what lets legs that measure nothing comparable sit in the same pool: a cosine and an unbounded BM25 score never have to agree on a scale. And a leg with nothing useful to say abstains rather than emitting a flat ranking that would poison the pool, so fusion degrades to whichever legs survived.

That is the whole reason the highlighted legs matter. They are deterministic and embedder-free, so with no embedding model at all, retrieval keeps working instead of failing. Each hit records its provenance, so an answer can name the note it came from.

The lexical leg is dotted because it is exactly that: optional. Build it with /lexical and it joins the same fusion, strong on the rare tokens, proper nouns, and dates that a semantic index is weakest on.

Measured

Every number below comes from the harness in evals/, run against the product path rather than a benchmark-only shortcut. Silica does not claim state of the art, and these say why: the samples are small, the judge is a local-grade model, and LoCoMo here is 2 of its 10 conversations. They are not comparable to what vendors report. They are something vendor numbers usually are not, which is re-runnable on your own machine.

How they were run. LoCoMo ingests two of the ten conversations through the production FSM (fsm-extractive) and answers them with the production agent loop, deepseek-v4-flash as both answer and judge model, retrieval top-10 through the bge-reranker-v2-m3 cross-encoder. MuSiQue is retrieval only, no answer model, embeddings plus co-occurrence fused at k=10. The three vault rows are the deterministic tier of the golden harness against a live 758-note Obsidian vault, frozen in evals/golden/baseline.json. Additional evaluation probes in evals/ measure FactScore factual precision (factscore.py), claim span attribution (probe_explain_spans.py), LongMemEval long-memory retention, and paired statistical significance testing (paired_stats.py).

uv run python -m evals.golden --vault ~/path/to/vault
uv run python -m evals.musique --vault BENCH_DIR --corpus musique_corpus.json --questions musique.json --load --index
uv run python -m evals.locomo --data locomo10.json --run-root RUN_DIR \
  --conversations conv-26,conv-47 --ingest fsm-extractive --answer agent

And the numbers that do not flatter. The same frozen baseline reports 0.33 agreement between /organize and the folders the human had already chosen, and 0.11 recall for concept-expanded correlation. They ship unedited next to the good ones.

See your vault

Both views render the structure your notes already have, locally, off the same co-occurrence graph the retrieval legs use.

Point it at code

Set SILICA_VAULT to a repository instead of a note folder and Silica keeps a human-readable map of the code under docs/silica/, kept honest against git.

• /nucleate <file> extracts a shallow AST skeleton with tree-sitter (signatures, structure, imports) and turns it into a markdown note, stamped with the commit it was verified against.
• /wiki grows that into a behavioral wiki: an ARCHITECTURE.md plus one note per subsystem.
• /stale flags notes whose source changed in shape since you documented it, meaning a signature or control-flow change rather than a reformat. /impact maps changed files to the notes they affect. You re-document what actually moved, not the whole tree.

The point is the loop, and git is what closes it:

flowchart TD
    SRC["Source file"] -- "/nucleate" --> N["Note in docs/silica/<br/>AST skeleton, stamped<br/>code_ref: the verified sha"]
    N -- "/wiki" --> W["ARCHITECTURE.md<br/>+ one note per subsystem"]
    N --> GIT["You keep committing"]
    GIT -- "/stale" --> D{"Shape changed<br/>since code_ref?"}
    D -- "cosmetic only" --> Q["Stays quiet"]
    D -- "signature or control flow" --> SRC

    style D fill:none,stroke:#3987e5,stroke-width:2px
    style Q fill:none,stroke:#3987e5,stroke-width:2px

_{A reformat is not a documentation debt. Only a real shape change is, and that is the difference /stale is built to make. /impact cuts the same question the other way: from a diff to the notes that document those files, plus their 1-hop neighbors.}

One artifact, two readers: a human reads it as a current map of the repository, and a coding agent reads it over the MCP server to ground its work in the real structure instead of re-deriving it every session.

How the guardrail works

You already let deterministic tools reject and rewrite your work every day. You do not trust those tools, you trust the guardrail they enforce. Silica puts an LLM's edits behind the same kind of guardrail:

Design contracts

Silica is not a free-form agent. Every vault mutation passes through a finite-state machine, and these are the invariants it enforces:

• Single entry point. All nucleation flows through the Injector FSM. There is no side channel that writes to the vault.
• Verify or revert. A post-write mismatch raises VerifyMismatchError and rolls the write back.
• Graph-safe moves. Renames, merges, and splits redirect incoming links atomically.
• Zero-trust ingress. External content such as web search results can only land in Inbox/, and reaches the vault only through explicit staging and FSM review.
• Layered rollback. /undo (per note), /revert (per run), and optional SILICA_GIT_COMMIT=auto stack as independent safety nets.

Scope of the claim. The guardrail is enforced today on the normal write path. It is not yet crash-verified: a harness that kills the process mid-write to prove the invariants survive failure is in progress. Read it as enforced control flow, not as a proof under adversarial faults. Back your vault up before letting any tool rewrite it, and keep git as the byte-level backstop.

Command reference

Ask and audit (read-only)

Bring in and reshape

Indexes /embed · /cooccur (embedder-free) · /lexical (BM25 and fuzzy)

Visualize /graph [out.html] · /map <note> (radial mind-map canvas)

Codebase /wiki · /stale · /impact [<range>]

Undo, inspect, and queue

System & Settings

Configuration

silica init writes the essentials. The full list with defaults is in .env.example.

Status

Everything under Available now ships in the current release. Everything below it does not.

Available now. Note nucleation, structural audit, semantic and embedder-free search, graph-safe refactor / dedup / merge, graph and mind-map export, codebase skeletons with git-backed /stale and /impact, the code wiki, layered /undo and /revert, the git safety net, the MCP server, and the Claude Code plugin.

Next, and it is the one that decides the rest. Upkeep runs when you ask for it (/curate, /organize, /stale, /report). Being answerable for a folder means noticing without being asked, so the next work is scheduled upkeep: a folder watch, an audit that runs on its own, and a queue of changes waiting for your yes. Until it ships, read the claim at the top of this file as on demand.

In progress. Richer codebase coverage across more languages, PDF/DOCX/TXT nucleation, the live Obsidian bridge, and the crash harness backing the guardrail.

Planned. Image nucleation, MCP packaging for non-Claude agents.

References

• From Agent Loops to Structured Graphs: A Scheduler-Theoretic Framework for LLM Agent Execution (arXiv:2604.11378, 2026)
• Goal-Autopilot: A Verifiable Anti-Fabrication Firewall for Unattended Long-Horizon Agents (arXiv:2606.11688, 2026)
• Is Your Agent Playing Dead? Deployed LLM Agents Exhibit Constraint-Evasive Fabrication and Thanatosis (arXiv:2606.14831, 2026)
• Reliable Graph-RAG for Codebases: AST-Derived Graphs vs LLM-Extracted Knowledge Graphs (arXiv:2601.08773, 2026)
• Predicting new research directions in materials science using large language models and concept graphs (Nature Machine Intelligence, 2026)

Silica's embedder-free near-duplicate detection (/dedup) is inspired by and ports the MinHash design from Graphify.

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md for setup and conventions (English-only, conventional commits). By contributing you license your work under AGPL-3.0-or-later. For security issues follow SECURITY.md and do not open a public issue.

License

GNU Affero General Public License v3.0. Strong copyleft, no permissive fallback: anything incorporating Silica must itself be AGPL-3.0 with complete corresponding source offered to its users, and §13 extends that to network use, so a modified version run as a hosted service owes source to the people using it. Full text in LICENSE.