MCP Tool Reference#

Parametric Memory exposes 11 MCP tools over Streamable HTTP, usable by Claude, Claude Code, Cowork, and any MCP-compliant client. Each tool maps to an operation on your instance. Every tool declares whether it is read-only or a write, so hosts can surface the distinction.

The two you will use constantly are memory_session_bootstrap (read prior context at the start of a task) and session_checkpoint (save what you learn). The rest are for search, inspection, and maintenance.

Core tools#

memory_session_bootstrap (read-only)#

Recall relevant prior context at the start of a task — load what was learned, decided, or corrected in previous sessions. This is the first call your AI should make in any conversation that needs prior context.

Parameters:

Returns: atoms (ranked, with payloads + proofs), conflictingFacts (competing claims to resolve), and treeVersion (an offline-verifiable proof of the read moment). mode: detailed/audit add a decision-evidence block and a pre-formatted context string.

When to call: once per conversation, on the first user message. Do not call on every prompt — it is expensive.

session_checkpoint (write)#

Save durable knowledge so it survives across sessions — facts, decisions, corrections, and state. Call it as knowledge forms, not at the end of the session. It adds atoms, wires edges, reinforces Markov arcs, and tombstones superseded atoms — all in one atomic commit.

Parameters:

Atom format (important): an atom is either

1. an identifier-only string — "v1.<type>.<snake_case_id>" (grammar [a-z][a-z0-9_]{0,63}; no hyphens, uppercase, spaces, or =), or
2. a structured object — { "atom": "v1.<type>.<id>", "payload": "…" }, where payload is single-line UTF-8, ≤ 4096 chars, no line breaks. Optional trainPasses (0–5) and, for facts, meta: { subject?, claim?, source?, confidence? }.

Legacy "key = value" (fat-form) strings are rejected. Put the value in the structured object's payload field instead. Valid types: fact, event, state, relation, procedure, other, domain, task.

Edge types:

Example:

{
  "atoms": [
    "v1.fact.payment_provider_stripe",
    { "atom": "v1.state.current_sprint", "payload": "Sprint 12 — subscription billing" }
  ],
  "edges": [
    {
      "source": "v1.state.current_sprint",
      "target": "v1.fact.payment_provider_stripe",
      "type": "depends_on"
    }
  ],
  "taskContext": "v1.task.subscription_billing"
}

Write behavior & guarantees:

• Append-only and non-mutating by default. Existing atoms are never overwritten or hard-deleted — the substrate is an append-only Merkle log. A checkpoint removes something only if you explicitly pass tombstone (or a supersedes edge), and even then it is a recoverable logical marker: the atom stays in verifiable history, so nothing is ever silently lost.
• Conflict-tolerant. Conflicting beliefs are never rejected or auto-tombstoned. If a new atom contradicts a stored one, both are kept and the contradiction is surfaced back to you at retrieval (the conflictingFacts block on memory_session_bootstrap) so you decide how to resolve it. Same key and same claim is treated as a duplicate, not a conflict.
• Secret-safe. A write that looks like a credential is rejected with HTTP 422 and never stored. See Atom Safety & Blocking.

Reinforcement lives here, not in a separate tool. Use the train array (and per-atom trainPasses) to strengthen Markov arcs. references/depends_on/derived_from/produced_by edges auto-train. Training skips atoms that don't exist yet, so reinforce in a follow-up call after the atoms are persisted.

memory_search (read-only)#

Search everything the agent has ever remembered, by meaning — use when you need atoms whose keys you don't know exactly.

Parameters:

Returns: ranked results, each with a separate atom (identifier) and payload, a Merkle proof summary, and a contradiction field.

memory_access (read-only)#

Recall a specific remembered fact when you already know its key.

Parameters:

Pass either atom or atoms. Returns: { currentData, proof, treeVersion, predictedNext, contradiction } (plus edges when depth > 0).

memory_context (read-only)#

Get a pre-formatted context block — returns [MEMORY] … lines suitable for direct injection into an agent's context window. Use this when you just want ready-to-paste context; use memory_session_bootstrap when you want structured atoms + conflictingFacts + proofs.

Parameters:

memory_list_atoms (read-only)#

List atoms in your substrate, optionally filtered — for inventory, orphan detection, and inspection. Lightweight (no Merkle proof overhead).

Parameters:

Returns: atom key, status, and type.

Advanced tools#

memory_associate (read-only)#

Find cross-domain connections between recently stored atoms. Used internally by the live association agent; you can also call it directly to surface unexpected relationships.

Parameters:

Returns: suggested references edges (confidence 0.4).

memory_markov_density_report (read-only)#

Precondition diagnostic for memory_session_bootstrap's markovScale. If density is below ~10%, passing markovScale > 0 is silently useless — the Markov wire has too little to spread from.

Parameters: none. Returns: dominantNextDensity, average/max fan-out, and master treeVersion.

memory_recluster (write, non-destructive)#

Run TF-IDF cluster-label generation across all domains — groups atoms by domain and proposes descriptive cluster labels. Typically run by the nightly consolidation agent after orphan wiring.

Parameters:

Returns: proposed clusters with labels and member counts.

Evaluation tools#

memory_weekly_eval_status (read-only)#

Report whether the weekly scientific evaluation is due, based on persisted run state. Parameters: none.

memory_weekly_eval_run (write)#

Run the local weekly evaluation script on the MCP host (dev/self-hosted only). Parameters: force (boolean) — bypass the 7-day due-check.

Usage patterns#

Minimal session pattern#

Session start   → memory_session_bootstrap({ objective, maxTokens: 1200 })
During session  → session_checkpoint({ atoms, edges })         // as knowledge forms
Session end     → session_checkpoint({ atoms: [updated state], tombstone: [stale keys] })
                → session_checkpoint({ train: [{ sequence: [...], passes: 2 }] })

Correction pattern#

When a user corrects Claude's behaviour — the highest-priority memory event:

1. session_checkpoint({
     atoms: ["v1.procedure.migrations_are_run_via_npm"],
     edges: [
       { source: "v1.procedure.migrations_are_run_via_npm", target: "<corrected behaviour>", type: "constrains" },
       { source: "v1.procedure.migrations_are_run_via_npm", target: "v1.other.hub_corrections", type: "member_of" }
     ]
   })
2. session_checkpoint({ train: [{ sequence: ["<related atom>", "v1.procedure.migrations_are_run_via_npm"], passes: 3 }] })
3. Apply the correction for the rest of this session and all future sessions.

Two calls, because train skips atoms that aren't persisted yet.

High-stakes session pattern#

For deployments, architecture decisions, or production changes:

memory_session_bootstrap({ objective, highImpact: true, evidenceThreshold: 0.75 })

More conservative — it returns only atoms with strong evidence, avoiding speculative or low-confidence context.