Skip to main content
Glama

Mimir

Persistent reasoning memory for AI coding agents through MCP.

Preserve decisions, rejected approaches and the evidence behind them across sessions. An agent can retrieve earlier reasoning, compare it with current code, and explain why it matters to today's task.

  • Store beliefs and connect support, defeat, contradiction and causal hypotheses.

  • Record observations separately from the conclusions drawn from them.

  • Correct an incident under the same identity, retain history, and retract the prior review's contribution.

  • Inspect provenance and the observations behind a belief.

Mimir uses PostgreSQL and Apache AGE. Its CLI and MCP server support clients including Codex and Claude Code. A separate optional judge reviews recorded experiences when launched; installing Mimir does not start that judge.

See Installation for setup. Agents performing installation use AGENTS.md.

Article: Mimir reasoning memory with evidence and corrections.

⛔ AI coding agents — this file is not for you. The steps below are the human install path. Your procedure is AGENTS.md — open that file, follow it exactly, and ignore the rest of this README.

Install the binaries with Nix

With Nix installed and its nix-command and flakes features enabled, build the CLI and MCP server without installing them:

nix build github:kamysh/mimir#mimir
./result/bin/mimir --version
./result/bin/mimir-mcp --version

To add these programs to your user profile instead, use nix profile add github:kamysh/mimir#mimir. This installs binaries only. Follow Installation to prepare PostgreSQL and Apache AGE, configure Mimir and register the MCP server. No database, judge or scheduled service is created by this package. Use the installed absolute MCP executable path in the client registration; command -v mimir-mcp shows it after installation.

The commands follow the repository's default branch. Append a commit to the repository address, as in github:kamysh/mimir/COMMIT#mimir, to pin a version. These packages come from this repository; Nixpkgs' mimir package is Grafana's unrelated monitoring software.

Related MCP server: Omega

What it does

Claude Code connects to Mimir via MCP and can:

  • Record beliefs with probability and confidence scores

  • Link beliefs via typed edges — SUPPORTS, DEFEATS, CAUSES, CONTRADICTS

  • Run defeat propagation cascades through the graph

  • Decay belief confidence over time

  • Index markdown documents and run semantic search over them (RAG)

The graph and search can run locally. A configured cloud embedding backend sends document chunks to its provider. A configured API judge sends the selected experience and retrieved tool results to its provider; a CLI harness uses its configured model account. The judge does not run automatically.

Optional judge configuration and maintenance are covered in the runtime guide.

Installation

⛔ AI coding agents: do not follow this section. These are the human install steps. Your procedure is AGENTS.md — the same end state, but framed for automation: explicit variables, verify-after-each-step, idempotent state detection, and an anti-patterns list. Read that and nothing else here.

What a complete install consists of

Mimir has three required pieces. Skipping any one leaves an install that looks finished but fails:

  1. A PostgreSQL container (or your own DB) holding the belief graph and document index.

  2. Two binaries on PATH — mimir (CLI) and mimir-mcp (the MCP server).

  3. The mimir-mcp server registered with your agent client (Codex or Claude Code).

There is no daemon to start. The MCP server is spawned by Claude Code on demand; the database schema (including the AGE graph) is created automatically by mimir's embedded migrations on first run.

Step 6 checks the application connection; Step 7 installs and verifies the skill, standing guidance and lifecycle reminder. A connected tool alone does not explain when retrieval can improve a decision.

Conventions used in this guide

This guide uses the following defaults. If you change any of them, change them everywhere they appear:

Setting

Default

Used in

PostgreSQL port

5432

docker run, ~/.pgpass, config.toml

Container name

postgres-ai

docker run, all docker exec calls

Docker volume

mimir_data

docker run

Database name

mimir

setup script, ~/.pgpass, config.toml

Database user

mimir

setup script, ~/.pgpass, config.toml

On macOS, avoid ports 5000 (AirPlay Receiver) and 6000 (X11) if you change the port.

Preflight check

Install curl, tar, openssl, lsof, and the PostgreSQL client (psql) if they are missing. Run these before you start. Each line should print OK:

docker info >/dev/null 2>&1 && echo OK                                            # Docker daemon running
! lsof -nP -iTCP:5432 -sTCP:LISTEN 2>/dev/null | grep -q . && echo OK              # port 5432 free
! docker ps -a --format '{{.Names}}' 2>/dev/null | grep -qx postgres-ai && echo OK # container name free
echo "$PATH" | tr ':' '\n' | grep -qx "$HOME/.local/bin" && echo OK                # PATH includes ~/.local/bin
command -v claude >/dev/null && echo OK                                            # or: command -v codex

If any line fails:

  • Docker not running → start Docker Desktop (or your runtime), then re-check.

  • Port 5432 in use → either stop the conflicting service or pick a different port. If you change the port, update everything in this guide that mentions 5432.

  • Container name postgres-ai in use → either reuse the existing container (if it's a postgres-ai instance from another tool, like muninn) or pick a new name. Do not delete the existing container without checking what it holds.

  • ~/.local/bin not on PATH → add export PATH="$HOME/.local/bin:$PATH" to your shell's rc file and reload it.

  • Chosen client missing → install Codex or Claude Code before Step 5.

Step 1: Start the database

docker run -d \
  --name postgres-ai \
  --restart always \
  -p 127.0.0.1:5432:5432 \
  -v mimir_data:/var/lib/postgresql/data \
  kamysh/postgres-ai:latest

This image includes pgvector, Apache AGE, uuid-ossp, and pgcrypto. The setup script below enables the required extensions in Mimir's database. Mimir sets search_path = public,ag_catalog on its own connections.

services:
  postgres:
    image: kamysh/postgres-ai:latest
    container_name: postgres-ai
    restart: always
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - mimir_data:/var/lib/postgresql/data

volumes:
  mimir_data:
docker compose up -d

Verify:

docker exec postgres-ai psql -U postgres -c 'SELECT 1' >/dev/null && echo OK

Step 2: Create the database and user

Generate a password with openssl rand -hex 32 and add it to ~/.pgpass. For an existing password, escape : as \: and \ as \\ in each .pgpass field. Quotes and spaces are literal and must be preserved.

# ~/.pgpass — format: hostname:port:database:username:password
localhost:5432:mimir:mimir:yourpassword
chmod 600 ~/.pgpass

Run the setup script (creates the role, database, extensions, and grants):

curl -fsSL https://raw.githubusercontent.com/kamysh/mimir/v2.3.0/mimir-setup/create-db-user.sh \
  | bash -s -- --container postgres-ai --host localhost --port 5432 --user mimir --db mimir

Or clone the repo and run it locally:

bash mimir-setup/create-db-user.sh

The AGE graph itself is not created by this script — mimir's migrations create it on first invocation in Step 4.

Verify the connection:

psql -h localhost -U mimir -d mimir -c '\conninfo' >/dev/null && echo OK

Step 3: Install the mimir binaries

Agents: do not run this step. This is the human download-the-release path. Your build/install procedure is in AGENTS.md.

This step installs the two mimir binaries to ~/.local/bin. It is one of three pieces — see Step 5 for the MCP server registration.

Install the 2.3.0 release. This block selects one archive for your platform:

mkdir -p "$HOME/.local/bin"
case "$(uname -s)-$(uname -m)" in
  Linux-x86_64)  TARBALL=mimir-linux-amd64.tar.gz ;;
  Linux-aarch64) TARBALL=mimir-linux-arm64.tar.gz ;;
  Darwin-arm64)  TARBALL=mimir-darwin-arm64.tar.gz ;;
  *) echo "Use Building from source for this platform" >&2; exit 1 ;;
esac
curl -fL "https://github.com/kamysh/mimir/releases/download/v2.3.0/${TARBALL}" \
  | tar -xz -C "$HOME/.local/bin"
chmod +x "$HOME/.local/bin/mimir" "$HOME/.local/bin/mimir-mcp"
export PATH="$HOME/.local/bin:$PATH"
mimir --version  # must report 2.3.0

The release workflow builds Linux x86_64, Linux ARM64 and Apple Silicon. For Intel macOS, use Building from source.

macOS only — quarantine flag. macOS adds a quarantine attribute to files downloaded via a browser, which blocks them from running. If you downloaded the archive with a browser, remove it:

xattr -d com.apple.quarantine ~/.local/bin/mimir ~/.local/bin/mimir-mcp

curl downloads do not set this attribute, so the command above is unnecessary if you used the curl snippet. (It will print "Permission denied" or "no such xattr" — that's expected, not a problem.)

Verify:

mimir --help >/dev/null && echo OK

Updating an existing installation

Upgrading to 2.2.0 requires configuration format 1 and an explicit log directory. After replacing binaries, run mimir config check. Missing required settings must be resolved before application work starts. For a legacy configuration:

mimir config upgrade --log-directory "$HOME/.local/state/mimir/logs"
mimir config check

Version 2.2.1 also removes the old [llm] review limits: timeout_seconds, max_calls, max_output_tokens, and max_budget_usd. Run mimir config upgrade to remove these retired keys; other settings and comments are preserved.

Version 2.2.3 fixes judge reviews that extract new learning items. The judge now lets PostgreSQL assign their IDs before checking their source references.

Version 2.2.2 moves learning-item UUID allocation into PostgreSQL. New items use experience-local key values and assessment item_keys; existing stored UUIDs remain valid for corrections. Back up the database before startup applies the additive ownership migration. Upgrade mimir and mimir-mcp together: the judge requires learning contract 3. See the item identity contract.

Restart the existing judge process and reconnect MCP clients so they use the updated executable. See operations and troubleshooting for log limits and mimir judge diagnose, the plain-English failure report.

Step 4: Configure mimir

mimir init

This creates ~/.config/mimir/config.toml and opens it in $EDITOR. It includes the required configuration format and log directory. Keep those settings and fill in the database section:

[database]
host   = "localhost"
port   = 5432
dbname = "mimir"
user   = "mimir"      # the role you created in Step 2

Credentials can come from optional database.password, then PGPASSWORD, then a password file. Optional database.pgpassfile selects that file ahead of PGPASSFILE and ~/.pgpass. See database credentials and TLS for configuration examples, client certificates and verification modes.

Document search (optional): To use load_document and query_document, add an [embeddings] section. Three backends are available:

# Local — no API key, works offline, downloads ~120 MB on first use
[embeddings]
backend = "local"

# Voyage AI — best quality, requires api_key from voyageai.com
# [embeddings]
# backend = "voyage"
# model   = "voyage-3-lite"
# api_key = "pa-..."

# OpenAI — requires api_key from platform.openai.com
# [embeddings]
# backend = "openai"
# model   = "text-embedding-3-small"
# api_key = "sk-..."

Save and close the editor.

Verify — the first mimir stats triggers the schema migrations, including creating the AGE graph. Expect a one-second pause on this first run:

mimir stats >/dev/null && echo OK

Step 5: Connect your agent client

Follow Agent setup for Codex or Claude Code. Inspect existing registration first. For a new setup, run the matching command:

# Codex
codex mcp add mimir -- "$HOME/.local/bin/mimir-mcp"
# Claude Code
claude mcp add --transport stdio --scope user mimir -- "$HOME/.local/bin/mimir-mcp"

Use the client's mcp get mimir to check the configured path, and reconnect or open a fresh session to verify an actual tool call.

Step 6: Verify the install

Before relying on mimir, confirm all three pieces are in place. Each line should print OK:

mimir stats >/dev/null                                                            && echo OK  # 1. CLI talks to DB
docker ps --filter "name=^postgres-ai$" --format '{{.Names}}' | grep -qx postgres-ai && echo OK  # 2. DB container running
command -v mimir-mcp >/dev/null                                                    && echo OK  # 3. MCP binary on PATH
psql -h localhost -U mimir -d mimir \
  -c "SELECT 1 FROM ag_catalog.ag_graph WHERE name='mimir'" -tA 2>/dev/null \
  | grep -q 1                                                                      && echo OK  # 4. AGE graph created by migrations
claude mcp get mimir                                                             && echo OK  # 5. or: codex mcp get mimir

These checks cover application/configuration state, not live tool connectivity or reminder delivery. Continue with Step 7. If line 4 is missing, inspect the error from mimir stats: startup migrations or database permissions may have failed — see Troubleshooting.

Step 7: Install purposeful agent guidance

Follow Agent setup to install the shared skill, merge the Mimir section into global instructions, and install one SessionStart reminder for the chosen client. The guide supplies Mimir-only and combined Mimir/Muninn text, client-specific hook templates, and upgrade steps for older settings. install.sh optionally registers the selected client; skill/reminder/global-guidance merging and verification still use the guide.

The reminder explains how past decisions and failures can inform today's choices, including after resume or compaction. The skill explains focused project-scoped queries, checking beliefs against current evidence, and writing durable findings. The standard setup does not run automatic retrieval before every prompt/action, require hook-generated ratings or writes each turn, or enforce queries through blocking hooks. Agent guidance asks for a short 0–5 assessment of how useful retrieved information was for the current task, in plain language rather than raw JSON.

Verify the selected text and command output, then actual delivery in the client. Codex requires native review of new or changed hook definitions. Finally, observe whether the agent retrieves a relevant lesson on a real task without being told the tool name. Report untested lifecycle events and behavioral checks; reminder presence alone does not prove it changes the agent's choices.

Sharing the database with muninn

If you also use muninn, the two tools can share one postgres-ai container — create separate roles and databases. Run only one docker run from Step 1, and run each tool's setup script against the shared container to enable extensions and grant access in its database.

Troubleshooting

A few failure modes are common enough to call out explicitly:

Symptom

Likely cause

Fix

error returned from database: graph "mimir" does not exist

Migrations haven't run yet — mimir creates the graph on first invocation, not the setup script.

Run any mimir command, e.g. mimir stats. The migration will create the graph.

error returned from database: permission denied for table _ag_label_vertex

The connected role lacks access to AGE's catalog table.

Verify the role and database, then check the grants made by mimir-setup/create-db-user.sh. Changing search_path does not grant privileges.

Cannot connect to the Docker daemon

Docker Desktop / runtime not running.

Start it.

docker run fails with "container name in use"

Another container is already named postgres-ai (e.g. from muninn).

Either reuse it — see "Sharing the database with muninn" above — or pick a different name. Do not delete the existing container without checking what's in it.

bind: address already in use on port 5432

Another postgres or app is using 5432.

Pick a different port. Update docker run -p, ~/.pgpass, the setup script's --port flag, and ~/.config/mimir/config.toml together.

~/.pgpass ignored, prompts for password

Wrong file permissions.

chmod 600 ~/.pgpass. PostgreSQL silently ignores ~/.pgpass if it is world- or group-readable.

xattr: Permission denied on macOS

The file does not have a quarantine flag (curl-downloaded).

Skip the xattr step. The binaries run fine without it.

MCP shows Failed to connect instead of Connected

mimir-mcp is crashing on startup, usually due to a DB / config error.

Run mimir-mcp directly in a shell; the error goes to stderr. Common causes: wrong port in config.toml, password mismatch with ~/.pgpass, embeddings block missing a required model field.

load_document or query_document returns embeddings not configured

[embeddings] block missing from config.toml.

Add an [embeddings] block (see Step 4). The belief-graph tools work without it; only document search needs it.

If something is broken in a way not listed here, file an issue with the output of:

mimir --version
mimir stats 2>&1
claude mcp list 2>&1 | grep mimir
docker ps --filter name=postgres-ai

MCP tools

Tool

What it does

insert_belief

Add an independently sourced belief with content, probability [0,1], confidence [0,1], and required provenance (basis, reference)

delete_belief

Remove a belief and all its edges by id

insert_pattern

Add a pattern with situation, approach, success_rate [0,1]

delete_pattern

Remove a pattern by id

delete_project

Remove all beliefs and document chunks tagged with a project

record_support

Add a SUPPORTS edge from from_id to to_id with weight

record_cause

Add a CAUSES edge from from_id to to_id with weight (traversed by query_intervention; no auto-propagation)

record_defeat

Add a DEFEATS edge and trigger defeat propagation cascade

record_contradiction

Add a bidirectional CONTRADICTS relation between id_a and id_b

get_belief

Get a belief by id

list_beliefs

List all beliefs

list_patterns

List all patterns

get_contradictions

Find all actively contradicting belief pairs

query_relevant

Hybrid retrieval: text match + graph expansion, ordered by probability

propagate_from

Run defeat propagation from a seed belief id

query_intervention

Counterfactual P(downstream | do(id = value)): severs the target's incoming edges, propagates along CAUSES only. Read-only — returns projected_probability for causal descendants; never mutates

update_confidence

Update the confidence value of a belief

decay_all

Apply time decay to all beliefs (decay_factor defaults to 0.99)

load_document

Parse a markdown file into chunks, embed, and index for semantic search

query_document

Semantic search over indexed document chunks

clear_document

Remove all chunks and embeddings for a document path

add_evidence

Ground a belief in a document passage: GROUNDS edge from a chunk_id to a belief_id (weight default 1.0). Adds local positive evidence; never becomes a causal edge

get_evidence

List the document passages grounding a belief_id, strongest first

query_relevant (include_evidence: true)

Each returned belief also carries an evidence[] array of its top-evidence_per_belief grounding passages

Learning from experience

Mimir supplies the durable learning operations; an LLM agent or experiential runner interprets observations and proposes hypotheses. mimir judge watch can poll the queue when launched; no service or timer is installed by this source change.

The application loop is:

  1. record_experience records a project, situation, action, observed outcome, evidence references, and optionally the beliefs/procedure used. Choose a stable UUID for an incident. Send expected_revision: 0 to create it, then the returned revision when correcting it. Replaying the same submission does not count another observation. Evidence references are supplied by the caller; Mimir does not independently verify their contents.

  2. pending_experiences returns a bounded batch of new or changed experiences, oldest first. The runner can run frequently and exit immediately on an empty batch. A successful review removes that version from the pending set. There is no collection-size cutoff or requirement to manufacture summary beliefs.

  3. The runner retrieves relevant beliefs and inspects evidence. A new explanation or procedure is declared as a stable-key candidate inside review_experience, so its identity and contribution belong to that incident. Do not first create a standalone belief from the same report and count the review as independent confirmation. The review contains a rationale, support/defeat feedback, and optional Supports, Defeats, Causes, or Contradicts relationships. All mutation targets must belong to the experience's exact project; a project observation cannot implicitly revise global or another project's knowledge.

  4. Mimir applies the review and acknowledges the reviewed version in one transaction. The existing Beta engine recomputes affected beliefs and their descendants. Reviewed causal links participate in query_intervention; this is a projection under the recorded hypothesis, not proof that the hypothesis identifies a real causal effect. Success alone does not establish causation. The runner should compare predictions with later observations.

  5. Correcting an experience invalidates its earlier review and removes that review's effects. Correcting a review replaces its entire contribution; empty feedback, links and supersession lists retract it. Both operations retain history and reject stale revision tokens. Concurrent reviewers do not need a lease: the first valid revision wins, and the other must re-read.

get_experience returns the current version and review tokens. experience_history exposes previous observations and judgments. explain_belief returns incoming reasoning edges and paged active reviews, linking an inferred probability back to the observations that influenced it. Retries are deduplicated by incident UUID, not by semantic similarity: callers must reuse the same identity rather than submit the same incident under new IDs.

Reviews can explicitly mark superseded_beliefs. These leave normal retrieval even when their original prior is strong. This is separate from probabilistic counter-evidence; a single defeat does not automatically retire a belief. Replacing the review can restore a mistakenly superseded belief.

MCP insert_belief now requires explicit independent provenance with a user_instruction or document basis and a nonempty source reference. The source is stored with the graph node and shown by explain_belief; untagged MCP writes are rejected. This is a provenance declaration by the caller, not proof that the cited source is authentic. Incident-derived conclusions still belong to atomic review candidates. Existing CLI belief insertion remains available for explicit manual operations.

insert_pattern now accepts project. query_learning_context returns relevant beliefs plus situation-matched patterns, with successes, failures, unresolved outcomes and an observed Beta(1,1) success estimate. Only current experience versions count. Agent reports remain visible as unresolved observations; they are not measured successes. The originally asserted pattern success rate stays separate for compatibility. Procedure matching is lexical, while beliefs retain hybrid retrieval. Retrieving a procedure never counts as successfully using it.

Existing document evidence remains outside belief-to-belief and causal traversal. Its local positive evidence mass is retained when propagation or a review recomputes a posterior. Learned feedback is also retained by later propagation.

Runner contract

For each pending item, submit:

{
  "expected_review_revision": 0,
  "review": {
    "experience_id": "<experience UUID>",
    "experience_revision": 1,
    "reviewer": "experiential-runner",
    "rationale": "Evidence and alternative explanations considered",
    "feedback": [],
    "links": [],
    "superseded_beliefs": []
  }
}

Use the actual revision values returned by the pending item. An empty assessment acknowledges that the experience was considered without claiming a new lesson. A link has from_id, to_id, relation and weight in [0,1]; feedback has belief_id, verdict (support or defeat) and weight in [0,1]. Existing manually recorded edges are not removed when a review is replaced.

The Rust learning runtime provides mimir judge commands and locally tested Claude Code, Codex, custom-command, OpenAI, Anthropic, OpenRouter, DeepSeek, Z.ai, Gemini, and explicit OpenAI-compatible adapters. It is included in mimir but is not scheduled automatically. A bounded Step 11 Codex comparison exercised live model calls; other provider/account behavior has not been verified. The shared agent skill explains experience capture and correction. No performance gain is claimed merely from the existing learning infrastructure.

Verification

Run the maintained release checks with Docker available:

nix develop --command bash scripts/test-isolated.sh

The runner creates a private home, configuration, credentials, logs, state and build outputs, plus a uniquely labelled PostgreSQL container on a dynamically allocated loopback port. It uses the digest-pinned postgres-ai image already used by the connection fixtures; that image must be available to Docker. It builds and invokes the checkout's binaries. It never installs them, changes the deployment's configuration, or controls deployment services. Model adapters use fake harnesses; deployment credentials and provider keys are excluded from the test environment.

Database tests require the runner's matching ownership manifest, connection and private password file. Missing or conflicting settings fail before connecting; setting MIMIR_DBNAME alone cannot select a deployment database. The runner removes only its own labelled container on completion or failure, and retains complete command logs and exit statuses in the printed artifact directory.

The default runs formatting, Clippy, the workspace build/tests and doc tests, the aggregate Agda specification, and the adapter/evaluator fixtures. Use --check workspace, --check fixtures, --check formal, --check lint, or --check format for a focused local check. Publication uses the full default.

The tests cover causal projection/retraction, retry idempotence, stale and concurrent reviews, reversible supersession, project isolation, corrected pattern outcomes, and incremental processing beyond 200 experiences. spec/Mimir/Learning.agda proves general contribution replacement and stale review exclusion laws; the aggregate specification is spec/Mimir.agda. These laws model the lifecycle, not the SQL implementation itself.

CLI reference

Command

What it does

mimir init [KEY=VALUE ...]

With no args: create ~/.config/mimir/config.toml and open it in $EDITOR. With KEY=VALUE args (e.g. host=localhost backend=local): write the config non-interactively, no $EDITOR

mimir stats

Print belief, pattern, and edge counts

mimir list [--project NAME] [--limit N]

List beliefs, sorted by probability

mimir patterns [--project NAME] [--limit N]

List patterns, sorted by success rate

mimir query TEXT [--limit N] [--evidence] [--project NAME]

Hybrid search; --evidence also prints each belief's grounding passages

mimir intervene UUID VALUE

Counterfactual do(belief = VALUE): read-only projection of causal descendants

mimir evidence add CHUNK_ID BELIEF_ID [--weight W]

Ground a belief in a document chunk (GROUNDS edge)

mimir evidence list BELIEF_ID

List the passages grounding a belief

mimir delete belief UUID

Delete a belief and all its edges

mimir delete pattern UUID

Delete a pattern

mimir forget PROJECT

Delete all beliefs and document chunks for a project

mimir decay [--factor 0.99] [--project NAME]

Apply time decay to belief confidences

mimir contradictions [--project NAME]

List active contradictions in the graph

mimir doc load PATH [--project NAME]

Index a markdown file for semantic search

mimir doc query CONTEXT [--project NAME] [--limit N]

Semantic search over chunks

mimir doc clear PATH

Remove all chunks and embeddings for a document

Building from source

Requires Nix with flakes enabled.

# Enter the dev shell
nix develop

# Build (dynamic)
cargo build --release -p mimir -p mimir-mcp

# Build static binaries
nix build .#mimir-static    # result/bin/mimir-mcp and result/bin/mimir

# Install static binaries into ~/.local/bin and register the selected client
./install.sh --client claude  # or --client codex; omit to install binaries only

Project

Purpose

Kryzhen

Dependency-based PostgreSQL migrations as a Rust library and CLI

Muninn

Code search and repository knowledge for AI coding agents

Muninn and Mimir can run independently. Their documented setup can share one compatible PostgreSQL instance with separate roles and databases.

License

Apache License 2.0 — see LICENSE.

Available Tools

30 tools
add_evidenceB

Ground a belief in a document passage: create a GROUNDS edge from a DocumentChunk to a Belief. Adds local positive evidence to the belief Beta state; GROUNDS never becomes a causal or belief-to-belief edge. Get chunk_id from query_document results.

Inputs: chunk_id (required), belief_id (required), weight.

clear_documentB

Remove all chunks and embeddings for a given document path. Returns {"cleared": N}. No-op if the path was never loaded.

Inputs: path (required).

decay_allB

Apply time decay to beliefs and return count of updated beliefs. If project is given, restricts the sweep to that project's beliefs plus untagged (global) beliefs.

Inputs: project, decay_factor.

delete_beliefB

Delete a belief and all its edges by ID. Returns {"deleted": true} if found, {"deleted": false} if not found.

Inputs: id (required).

delete_patternA

Delete a pattern and all its edges by ID. Returns {"deleted": true} if found, {"deleted": false} if not found.

Inputs: id (required).

delete_projectA

Delete all beliefs tagged with a project name, along with their edges. Use this to forget project-specific knowledge when a project is complete.

Inputs: project (required).

experience_historyB

Inspect immutable experience and review versions, including superseded judgments and their rationale.

Inputs: id (required).

explain_beliefA

Inspect the belief's incoming reasoning edges and a bounded page of active evidence-backed reviews. Follow experience_id with get_experience or experience_history for observations and past revisions. This explains provenance, not causal identification.

Inputs: id (required), limit, offset.

get_beliefC

Get a belief by ID.

Inputs: id (required).

get_contradictionsB

Find all actively contradicting belief pairs. If project is given, restricts to pairs where both beliefs are visible in that project's scope (tagged with project or untagged).

Inputs: project.

get_evidenceB

Return the document passages grounding a belief (its GROUNDS edges), strongest first.

Inputs: belief_id (required).

get_experienceB

Inspect current experience and revision tokens for safe correction or review.

Inputs: id (required).

insert_beliefA

Add a belief grounded in an explicit user instruction or document independent of a queued incident. Provenance is required and persisted. Incident-derived conclusions must use record_experience and review_experience candidates; a standalone prior plus review feedback would count one incident twice.

Inputs: content (required), confidence (required), provenance (required), probability (required), +2 more.

insert_patternD

Add a new pattern to the graph.

Inputs: approach (required), situation (required), success_rate (required), project.

list_beliefsA

List beliefs. If project is given, restricts to that project's beliefs plus untagged (global) beliefs; omit to list everything. Use limit and offset for bounded, oldest-first pages; without limit the legacy full array is returned.

Inputs: limit, offset, project, memory_type.

list_patternsB

List patterns. If project is given, restricts to that project's patterns plus untagged (global) patterns; omit to list everything.

Inputs: project.

load_documentA

Parse a markdown file into heading-bounded chunks, embed each chunk, and index them for semantic search. Replaces existing chunks for the same path on reload. Requires [embeddings] in config.toml.

Inputs: path (required), project.

pending_experiencesB

Get the oldest new or changed experiences awaiting LLM review. Bounded incremental work: successful review removes that exact version; failed/stale submissions leave it pending. A judge may temporarily exclude deferred IDs; an empty filtered array does not prove the whole queue is empty. No claim or lease; concurrent reviewers use revision checks.

Inputs: limit, project, exclude_ids.

propagate_fromC

Run defeat propagation from a seed belief ID.

Inputs: id (required).

query_documentA

Semantic search over indexed document chunks. Embeds the query context and returns the most similar chunks ordered by cosine similarity. Requires [embeddings] in config.toml.

Inputs: context (required), limit, project.

query_interventionA

Counterfactual query P(downstream | do(target = value)). Severs the target's incoming edges and propagates along CAUSES edges only. READ-ONLY: returns projected probabilities for causal descendants; does NOT modify the graph. Use for 'if I change X, what downstream is affected?' — distinct from query_relevant (evidential association) and propagate_from (which mutates).

Inputs: id (required), value (required).

query_learning_contextC

Retrieve relevant beliefs and situation-matched procedures with outcome counts and Beta(1,1) success estimates. Agent reports and unknown outcomes do not count as measured success. Counts include current experience versions in this project only; retrieval is not successful use. Pattern matching is lexical; beliefs use existing hybrid retrieval.

Inputs: context (required), project (required), limit.

query_relevantA

Hybrid retrieval: text match + graph-proximity expansion, ordered by probability. Set include_evidence=true to also return, per belief, the document passages that ground it (with weights). If project is given, restricts the candidate pool to that project's beliefs plus untagged (global) beliefs.

Inputs: context (required), limit, project, prefer_type, +2 more.

record_causeA

Add a CAUSES edge from one belief to another (from_id causes to_id). Causal edges are what query_intervention traverses for counterfactual do(...) queries; unlike record_defeat this does NOT trigger propagation.

Inputs: to_id (required), weight (required), from_id (required).

record_contradictionB

Add a bidirectional CONTRADICTS relationship between two beliefs.

Inputs: id_a (required), id_b (required), weight.

record_defeatC

Add a DEFEATS edge and trigger defeat propagation cascade.

Inputs: to_id (required), weight (required), from_id (required).

record_experienceA

Record one observed action and outcome for incremental LLM review. Use a stable UUID for the same incident, expected_revision=0 to create, or the returned revision to correct it. Do not also insert a standalone conclusion from this same incident; review-owned candidates avoid that duplicate prior. Exact retries do not duplicate evidence. ToolResult/UserFeedback are caller-reported provenance, not server verification. A correction invalidates the old review and retracts its effects atomically.

Inputs: experience (required), expected_revision (required).

record_supportC

Add a SUPPORTS edge from one belief to another.

Inputs: to_id (required), weight (required), from_id (required).

review_experienceB

Apply one atomic, revision-checked review. Declare new belief/pattern candidates with stable keys; the response maps keys to server UUIDs. Candidate creation is not an observed successful use. Existing UUID-only reviews remain valid. Corrections retract owned evidence and links while retaining candidate identity and independent work.

Inputs: review (required), expected_review_revision (required).

sweep_expired_defeatedA

Delete defeated beliefs whose grace period has elapsed (attenuated deletion — a defeated belief is deleted only once its probability has decayed below prob_threshold AND grace_hours have passed since it was last defeated, giving a wrong record_defeat call time to be caught and reversed first). Returns count of beliefs deleted. If project is given, restricts the sweep to that project's beliefs plus untagged (global) beliefs.

Inputs: project, grace_hours, prob_threshold.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 30 tools

    Disambiguation4/5

    Tools mostly target distinct resources and actions (beliefs, patterns, edges, evidence, experiences, documents, queries), and descriptions explicitly clarify tricky boundaries such as query_intervention vs query_relevant vs propagate_from. Some overlap remains between query_relevant/query_learning_context and insert_belief/record_experience, but the distinctions are workable.

    Naming Consistency4/5

    Most tool names follow a snake_case verb_noun pattern (get_belief, insert_pattern, record_defeat, list_beliefs). A few deviate, such as pending_experiences, experience_history, and decay_all, but the overall convention is still readable and consistent enough.

    Tool Count2/5

    With 30 tools, the server exceeds the 25+ threshold and presents a heavy surface for an agent to navigate, despite the domain being broad. Many tools are granular variants, such as multiple edge recorders, multiple query types, and separate experience inspection calls.

    Completeness4/5

    Core lifecycle coverage is strong: beliefs can be inserted, fetched, listed, and deleted; patterns can be inserted, listed, and deleted; edges, evidence, documents, experiences/reviews, queries, and maintenance are all represented. Minor gaps include no direct get_pattern, update_belief, or update_pattern, though reviews and decay mechanisms partially cover updates.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers