M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
W

witness

Community
Local memory & self-improvement engine that witnesses your growth as a developer.
How to install ↓ Compare GitHub source repository ↗
Category
Dev Tools #95 of 438
Stars
★ 10 Popular
Transport
stdio (local process)
Runtime
Node.js · Prebuilt binary
Credentials
No credential needed
License
MIT
Last commit
Tools
5
62FMRS · C

witness is a local-first MCP server acting as a growth memory engine for Claude Code and OpenCode. It captures sessions and distills observations and facets into a provenance-backed profile. Noted for its reflection-not-clone design, multilingual support, and pure-Go implementation, it fits developers wanting to track their evolution with privacy.

Strongest · Documentation 16/20 Weakest · Reliability 10/20

Reliability
10/20
Security and permissions
14/20
Maintenance
10/20
Documentation
16/20
Setup experience
12/20
Why each score
Reliability 10/20
The manifest and README agree on five MCP tools over stdio; the L0–L4 architecture, single-binary design, and SQLite store are internally consistent, and diagnostic entry points (witness doctor, distill status) exist. However, this is a static review: the supplied material shows no CI workflows or committed tests covering the handshake or error paths, and the ~448MB model download/embedder startup are dependency risks only partially mitigated by doctor. Score capped at/below 12 absent verifiable execution evidence.
Security and permissions 14/20
Strong local-first posture: data under ~/.local/share/witness at 0700/0600, pure-Go local embeddings, no cloud keys, SHA256 verification for custom model mirrors, and deletion limited to single observations — no red-line behaviors (no malware, credential theft, covert exfiltration, or irreversible destructive defaults), so security is scored well above the 0–4 red-line band. Deductions: distillation pipes session content through the user's Claude/OpenCode auth to an LLM provider, which sits in tension with the 'nothing leaves your machine' claim; auto_distill=true launches model work by default; and the lens system executes arbitrary user-supplied prompt directories with no third-party-content caution.
Maintenance 10/20
MIT license, version 0.8.0, documented npm Trusted Publishing workflow with idempotent releases, and an upgrade migration note (stale witness-distill sessions) indicate thoughtful maintenance. But with 8 stars, 5 open issues, and no evidence of commit cadence, release history, or a security-response channel, governance evidence is incomplete.
Documentation 16/20
Well-layered docs: architecture, a complete copy-paste lens example, full command reference, configuration table, platform matrix, backup/restore guidance including WAL corruption warnings, upgrade caveats, and honest limitation disclosures (unsupported platforms, partial unwire). Deductions: MCP tool parameters (e.g., record_observation fields) are not individually documented, and troubleshooting leans on doctor without worked examples; client config snippets are absent.
Setup experience 12/20
The npm path is simple (add plugin to opencode.; MCP auto-registers), and source installs have a one-command install.sh with an explicit platform table. Deductions: the Claude Code path requires building from source, a ~448MB first model download that must complete while the editor runs, wire/unwire being source-only commands, and npm excluding macOS Intel, Linux ARM, and Windows. Complexity and partial platform coverage keep this at/below 15.

Static review · not runListed 2026-09-08

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local filesConnects to a database

Best for

  • Developers who want to preserve learnings across AI coding sessions.
  • Those seeking a second brain / AI memory that their agent can query for thinking patterns.
  • Privacy-conscious users who require all data stay local.
  • People who want to track their growth as a developer over time.

Not for

  • Those needing project-level memory or codebase history (it focuses on the person, not the code).
  • Those needing cloud sync or multi-user collaboration (it's local-first).
  • Users unfamiliar with CLI or unwilling to run a local model download.
  • Proactive coaching expecting in-session suggestions or nudges (it's a tool, not a coach).

Required permissions

  • Reads user prompts and assistant messages captured by Claude Code hooks.
  • Reads OpenCode's local SQLite session database.
  • Accesses local file system for storing data (default `~/.local/share/witness/`).
  • Invokes `claude -p` or a private `opencode serve` runner for distillation.

Risks and side effects

  • Data is all local but requires regular backups; don't sync live data directory directly.
  • May require significant disk space as the model ~470MB and raw transcripts accumulate.
  • Uses LLM distillation which can incur compute and cost depending on runner configuration.
  • Ensure to use `witness export` for consistent snapshots for backup to avoid corruption.

Setup

Before you start

Runtime：Node.js · Prebuilt binary

Other optional settings (4)
WITNESS_HOME optional Optional override for the witness data directory (default ~/.local/share/witness/).
WITNESS_MODEL_BASE_URL optional Optional custom embedding model mirror URL; only needed when mirroring the model.
WITNESS_MODEL_SHA256 optional Optional checksum of the model file, required alongside WITNESS_MODEL_BASE_URL for custom mirrors.
WITNESS_TOKENIZER_SHA256 optional Optional checksum of the tokenizer file, required alongside WITNESS_MODEL_BASE_URL for custom mirrors.

For Claude Code, run ./install.sh claude to build, download the ~448MB model, and wire hooks and MCP. For OpenCode, run ./install.sh opencode to wire the local plugin and MCP, or use the npm package @witness-ai/opencode and add the plugin to opencode.json. Windows users can download a zip from releases and run witness.exe wire claude.

Check that it works

The client's tool list should show search_observations, get_facets, get_profile, record_observation, and delete_observation; then ask the client to call get_profile — a returned narrative profile proves the connection.

Troubleshooting

  1. Run `witness doctor` to check embedder, model, and archive health.
  2. Check `witness distill status` to ensure the background distillation worker is running.
  3. For OpenCode integration issues, confirm the plugin is properly registered.
  4. Verify model names in `config.toml` are valid.

Things to try

Once connected, you can ask your AI assistant things like:

  • Use search_observations to find sessions where I mentioned the migration failing on prod
  • Use get_profile to show my unified growth portrait
  • Use get_facets to list the current facets for the default lens with their change history
  • Use record_observation to record the decision I just made as an observation

Tools 5

search_observations read-only
Local vector semantic search over observations.
get_facets read-only
Get current structured facets.
get_profile read-only
Get the narrative profile (prose), optionally per lens.
record_observation writes
Agent records a decision-aware observation directly.
delete_observation destructive
Delete an incorrect observation.

Use cases

Retain learnings across AI coding sessions.
Track your thinking patterns, work habits, and cognitive traps while coding.
Ingest your own notes, articles, or text streams to see knowledge evolve.
Generate re-readable growth narratives for personal retrospectives.

Supported clients

Claude Desktop
OpenCode

Listed from the project's documentation, not tested by this site.

Overview

witness is a local-first memory and self-improvement engine for Claude Code and OpenCode. It captures your coding sessions and distills how your patterns, habits, and knowledge evolve over time — a person-centric growth archive with provenance, served via an MCP server and plain files as a single Go binary. Data stays local, supports English and Chinese multilingual embeddings, and defaults to your existing Claude Code or OpenCode auth for distillation, requiring no external services.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 63.3k · Tools 2 Compare with this →
Compare with other MCP servers

Source revision 6fe528d62e2b Data synced 2026-10-19 Read the FMRS scoring method