Mimir
Summary: Mimir is an MCP server that gives AI coding agents a persistent graph-backed reasoning memory for beliefs, evidence, experiences, and learned patterns.
Record, retrieve, list, and delete beliefs with probability/confidence, project scope, memory type, and required provenance.
Create, list, and delete patterns describing a situation, approach, and success rate.
Link beliefs with SUPPORTS, CAUSES, DEFEATS, and CONTRADICTS edges; defeat links trigger propagation.
Query relevant beliefs via hybrid retrieval, inspect contradictions, and explain belief provenance and grounding evidence.
Ground beliefs in document chunks, list their evidence, load markdown documents, run semantic document search, and clear documents.
Run graph operations: defeat propagation from a seed belief, read-only counterfactual causal intervention queries, confidence decay, and cleanup of expired defeated beliefs.
Manage project-scoped knowledge by bulk-deleting beliefs and tagged document chunks for a project.
Record observed experiences, list pending reviews, submit atomic revision-checked reviews with candidates/links/feedback, inspect experience history, and retrieve learning context with patterns and outcome counts.
Integrates with Apache AGE (the graph extension for PostgreSQL) to hold Mimir's reasoning graph: typed belief-to-belief edges (SUPPORTS, DEFEATS, CAUSES, CONTRADICTS), document-to-belief GROUNDS evidence edges, defeat-propagation cascades from a seed belief, contradiction discovery, and read-only counterfactual do(...) queries that traverse CAUSES edges to project downstream probabilities.
Uses PostgreSQL as the persistent store for the belief graph and the document index. Mimir creates its own schema, including the graph extension setup, via embedded migrations on first run and manages beliefs in PostgreSQL, provenance-tagged observations, patterns, versioned experiences and LLM reviews, document chunks and embeddings, plus project-scoped bulk deletion, time-decay sweeps and cleanup of expired defeated beliefs.
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 --versionTo 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:
A PostgreSQL container (or your own DB) holding the belief graph and document index.
Two binaries on
PATH—mimir(CLI) andmimir-mcp(the MCP server).The
mimir-mcpserver 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 |
|
|
Container name |
|
|
Docker volume |
|
|
Database name |
| setup script, |
Database user |
| setup script, |
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 codexIf 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-aiin 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/binnot on PATH → addexport 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:latestThis 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 -dVerify:
docker exec postgres-ai psql -U postgres -c 'SELECT 1' >/dev/null && echo OKStep 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:yourpasswordchmod 600 ~/.pgpassRun 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 mimirOr clone the repo and run it locally:
bash mimir-setup/create-db-user.shThe 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 OKStep 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.0The 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-mcpcurl 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 OKUpdating 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 checkVersion 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 initThis 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 2Credentials 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 OKStep 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 mimirThese 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 |
| Migrations haven't run yet — mimir creates the graph on first invocation, not the setup script. | Run any mimir command, e.g. |
| The connected role lacks access to AGE's catalog table. | Verify the role and database, then check the grants made by |
| Docker Desktop / runtime not running. | Start it. |
| Another container is already named | 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. |
| Another postgres or app is using 5432. | Pick a different port. Update |
| Wrong file permissions. |
|
| The file does not have a quarantine flag (curl-downloaded). | Skip the |
MCP shows |
| Run |
|
| Add an |
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-aiMCP tools
Tool | What it does |
| Add an independently sourced belief with |
| Remove a belief and all its edges by |
| Add a pattern with |
| Remove a pattern by |
| Remove all beliefs and document chunks tagged with a |
| Add a SUPPORTS edge from |
| Add a CAUSES edge from |
| Add a DEFEATS edge and trigger defeat propagation cascade |
| Add a bidirectional CONTRADICTS relation between |
| Get a belief by |
| List all beliefs |
| List all patterns |
| Find all actively contradicting belief pairs |
| Hybrid retrieval: text match + graph expansion, ordered by probability |
| Run defeat propagation from a seed belief |
| Counterfactual |
| Update the |
| Apply time decay to all beliefs ( |
| Parse a markdown file into chunks, embed, and index for semantic search |
| Semantic search over indexed document chunks |
| Remove all chunks and embeddings for a document |
| Ground a belief in a document passage: GROUNDS edge from a |
| List the document passages grounding a |
| Each returned belief also carries an |
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:
record_experiencerecords a project, situation, action, observed outcome, evidence references, and optionally the beliefs/procedure used. Choose a stable UUID for an incident. Sendexpected_revision: 0to 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.pending_experiencesreturns 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.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 optionalSupports,Defeats,Causes, orContradictsrelationships. All mutation targets must belong to the experience's exact project; a project observation cannot implicitly revise global or another project's knowledge.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.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.shThe 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 |
| With no args: create |
| Print belief, pattern, and edge counts |
| List beliefs, sorted by probability |
| List patterns, sorted by success rate |
| Hybrid search; |
| Counterfactual |
| Ground a belief in a document chunk (GROUNDS edge) |
| List the passages grounding a belief |
| Delete a belief and all its edges |
| Delete a pattern |
| Delete all beliefs and document chunks for a project |
| Apply time decay to belief confidences |
| List active contradictions in the graph |
| Index a markdown file for semantic search |
| Semantic search over chunks |
| 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 onlyRelated projects
Project | Purpose |
Dependency-based PostgreSQL migrations as a Rust library and CLI | |
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 toolsadd_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
Scored across 30 tools
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.
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.
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.
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
Related MCP Connectors
Long-term memory for AI coding agents: durable project facts, recalled by every MCP client.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Evidence-backed project memory and checkpoints for AI coding agents.
Shared project memory for AI coding agents: decisions, lessons, risks and tasks in one graph.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancePersistent memory and pattern learning for AI coding assistants via MCP.111 npm175MIT
- AlicenseNot gradedqualityAmaintenancePersistent memory for AI coding agents1,665 PyPI226Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides persistent memory for AI coding agents via MCP, allowing them to recall fragility, decisions, and bugs across sessions.636 npm3MIT
- AlicenseNot gradedqualityDmaintenancePersistent cross-session memory for AI coding assistants, automatically capturing and injecting context across sessions via MCP tools.13 npm11AGPL 3.0