@remembrance-ai/mcp-server

MCP stdio server for Remembrance. It lets agents query skills/resources, fetch details, submit feedback, propose new skills, review resources, and bootstrap a local TOFU attestation key.

Even as the standalone path, it runs the same loop the native plugins do: query to reuse what other agents already solved, then submit feedback and remembrances so the registry sharpens for the next agent. Your agent gets smarter, and the network gets smarter with it.

Install

npx @remembrance-ai/mcp-server

Use this standalone MCP server when your agent cannot install a native Remembrance plugin. Claude Code, Codex, Cursor, OpenClaw, VS Code, and OpenCode users should start with their native plugin path because those packages add skills/rules and hooks around the MCP tools.

Claude Code plugin install:

claude plugin marketplace add dreamarkinc/remembrance-skills
claude plugin install remembrance@remembrance

The claude plugin CLI works in any shell; the interactive /plugin slash command is the equivalent inside a running claude session.

Codex plugin install:

CODEX_CLI="${CODEX_CLI:-$(command -v codex || true)}"
[ -x "$CODEX_CLI" ] || CODEX_CLI="/Applications/ChatGPT.app/Contents/Resources/codex"
[ -x "$CODEX_CLI" ] || CODEX_CLI="/Applications/Codex.app/Contents/Resources/codex"
[ -x "$CODEX_CLI" ] || { printf '%s\n' "Codex CLI not found. Install the Codex CLI, or install or update the ChatGPT desktop app on macOS, then try again." >&2; exit 1; }
"$CODEX_CLI" plugin marketplace add dreamarkinc/remembrance-skills &&
  "$CODEX_CLI" plugin marketplace upgrade remembrance &&
  "$CODEX_CLI" plugin add remembrance@remembrance

After a Codex install or update, enter /hooks in Codex and confirm the Remembrance SessionStart, UserPromptSubmit, PostToolUse, and Stop hooks all show Active. Trust any marked Needs review. Changed hook definitions require review again.

If codex is not on your shell PATH, this checks the current ChatGPT.app bundle first and retains the legacy Codex.app compatibility path.

Cursor plugin install is managed from Cursor > Customize > Plugins or a team marketplace that imports packages/cursor-plugin from the public mirror. The plugin registers this MCP server automatically through its mcp.json.

OpenClaw plugin install:

openclaw plugins install clawhub:@remembrance/openclaw-plugin
openclaw remembrance setup

The OpenClaw plugin reads the same shared key config at ~/.config/remembrance/config.json, registers the Remembrancer skill, and adds conversation hooks around the MCP tools. Use standalone MCP only when a native plugin install is unavailable. Restart OpenClaw after setup, then run openclaw mcp doctor remembrance --probe.

VS Code agent-mode install: run Chat: Install Plugin From Source from the Command Palette and enter https://github.com/dreamarkinc/remembrance-skills.

OpenCode plugin install:

npx -y @remembrance-ai/opencode-plugin setup

Restart OpenCode after setup. The plugin adds bounded matching guidance before eligible model turns and observes lifecycle, tool, and completion events around the version-matched local MCP server.

Environment:

• REMEMBRANCE_API_URL: Remembrance API origin. Defaults to https://remembrance.dev.
• REMEMBRANCE_API_KEY: optional org API key for private/org-scoped access.
• REMEMBRANCE_API_KEY_ORIGIN: required when an environment API key is used with a custom REMEMBRANCE_API_URL; it must be that exact URL. The default https://remembrance.dev destination needs no extra binding. A shared config instead binds the key by storing apiKey and apiUrl in the same JSON file.
• REMEMBRANCE_ALLOW_PRIVATE_REGISTRY=true: explicit opt-in for an intentionally trusted private or link-local HTTPS self-hosted registry. Every remote registry requires HTTPS; only loopback development may use HTTP.
• REMEMBRANCE_API_TIMEOUT_MS: request timeout in milliseconds, capped at 60,000. The timeout covers response headers and the bounded response body.
• REMEMBRANCE_AGENT_KEY_PATH: optional local key path. Defaults to $XDG_CONFIG_HOME/remembrance/agent-key.json or ~/.config/remembrance/agent-key.json.
• REMEMBRANCE_PLUGIN_HOST: set by native plugin manifests (codex, claude_code, cursor, openclaw, vs_code, or opencode) so connection health can verify that host's local lifecycle. Leave unset for MCP-only installs.
• REMEMBRANCE_HEALTH_REPORTING=0: disables best-effort submission of bounded degraded-activation issue codes. Local diagnostics remain available.

Before diagnosing authentication, call run_connection_doctor. It performs a non-mutating authorized catalog read and reports transport, credential security, registry destination consistency, query readiness, organization submission authorization, plugin lifecycle, and signing readiness with exact bounded remediation. It never returns credentials, absolute paths, custom registry URLs, stable destination fingerprints, prompts, or repository content. The lower-level get_connection_status tool remains available when you need its underlying fields. The local server reports whether it used the environment, the shared config file, or no credential, plus the verified public/organization registry scope. It never returns the key. For local MCP it also reports local_signing_identity, its safe key ID, permission state, and a machine-readable repair action without returning the subject, key material, or local key path. A missing identity is initialized automatically on the first signed contribution. Do not treat an unset environment variable or an anonymous curl/browser probe as evidence that this local MCP process is anonymous. When a native plugin declares its host, the result also shows whether its startup, prompt, tool-observer, and completion hooks have been observed. MCP-only installs report that native lifecycle checks are not applicable.

If MCP registration itself failed and no Remembrance tool is visible, run:

npx @remembrance-ai/mcp-server doctor

Use --json for automation or --no-probe to skip the active catalog read. The standalone CLI can verify configuration, registry, auth, and read access, but it cannot claim that a host registered MCP; it tells you to rerun run_connection_doctor inside the host after update/reinstall and restart.

Local Identity Recovery

REMEMBRANCE_AGENT_KEY_PATH points at a local private key. Back it up like an agent identity secret, and never commit or share it. If the file is deleted, rerun bootstrap_agent_identity with no arguments; the server will create/register a new TOFU key with an opaque key-bound subject. The previous verified-tier history is not recoverable unless the original key file was backed up. Use REMEMBRANCE_API_KEY or a future registered-provider key when durable trust continuity matters.

Remote endpoint (no install)

The same proxy tools (everything except the local-only bootstrap_agent_identity and queue_private_skill_import) are hosted at a remote Streamable HTTP endpoint, so most clients need no local install. An optional org key goes in Authorization: Bearer <key>.

# Claude Code:
claude mcp add --transport http remembrance https://remembrance.dev/api/mcp

Cursor MCP fallback — ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "remembrance": { "url": "https://remembrance.dev/api/mcp" }
  }
}

Codex — ~/.codex/config.toml or .codex/config.toml:

[mcp_servers.remembrance]
url = "https://remembrance.dev/api/mcp"

Use the local stdio server below when you want bootstrap_agent_identity (TOFU key signing on your machine) or queue_private_skill_import (a zero-network, mode-0600 handoff for an admin dashboard import), which the remote endpoint cannot provide.

Every MCP tool publishes readOnlyHint, openWorldHint, and destructiveHint. Public submission tools are open-world. The networked propose_private_skill tool is non-read-only but closed-world because it can write only to the authenticated organization's private review queue and can never publish publicly. queue_private_skill_import is both closed-world and zero-network. These annotations help hosts review the real operation, but they never override host or tenant policy.

Managed host policy

An API key authorizes Remembrance; the agent host separately decides which MCP server, destination, and tools may run. For managed installs, allow the exact https://remembrance.dev/api/mcp endpoint or exact local stdio command, then expose only the organization tool inventory in skills/remembrancer/references/remembrance-setup.md. That reference contains current, copyable policy for Codex, Claude Code, Gemini CLI, OpenClaw, Cursor, and generic MCP clients, including host modes that suppress plugin hooks or plugin-provided MCP servers. The same guide is available at https://remembrance.dev/docs/remembrancer#private-repository-policy.

The recommended organization inventory covers discovery, invocation, bounded feedback/outcomes, submit_remembrance, propose_private_skill, and submit_suggestion. Dual-scope/public, resource, and identity tools are opt-in. If repository export remains denied, keep the denial and use local queue_private_skill_import; do not retry through another transport.

With an organization key, propose_skill_idea also stays in the organization review queue. Never remove or bypass the key to force a public candidate; submit privately, then use the reviewed public-propagation flow.

Claude Desktop (local stdio)

{
  "mcpServers": {
    "remembrance": {
      "command": "npx",
      "args": ["@remembrance-ai/mcp-server"],
      "env": {
        "REMEMBRANCE_API_URL": "https://remembrance.dev"
      }
    }
  }
}

Tools

• get_connection_status: inspect the active local/hosted transport, credential source, verified registry scope, and any declared native plugin lifecycle without exposing key material. Hosted MCP cannot read a local config file; local stdio can. A degraded native check submits only strict, content-free component/version issue codes for deduplicated admin triage; it never submits prompts, keys, repository paths, source content, or raw logs.
• run_connection_doctor: run the safe end-to-end connection check. It uses one status read and, by default, one catalog read; it does not create query demand, economics sessions, feedback, submissions, or review artifacts.
• list_skills: paginate the live skill catalog authorized for the current caller, or filter it by an indexed, normalized slug prefix. It is for resolving a known name or partial slug, not relevance discovery. It returns lightweight metadata and remembrance://skills/{slug} handles, not full private instructions.
• invoke_skill: load an explicitly selected skill by exact slug. It rechecks policy, resolves the current accepted version, marks the direct result selected/fetched, and returns post-use feedback and outcome instructions. Do not submit query-fit feedback for this direct selection. Resolve ambiguous known names with the list_skills slug-prefix filter; use query_skills for discovery, and never guess a slug.
• query_skills: find relevant skills and resources before non-trivial work; short follow-ups must be interpreted from the full conversation. Results include a high/possible/exploratory tier, a concise reason, approximate context tokens, verified-use evidence, risk, and correlation IDs. When a native host plugin supplies client_context.directive_id, preserve it so the query correlates and fulfills that plugin instruction. MCP-only clients do not create shown-directive events because no host instruction was injected; this telemetry never affects ranking. Read skill_access on every response. Under org_only, use only returned organization skills and do not substitute bundled or live public references; an unavailable query with an organization key fails closed for public-skill fallback because the current policy cannot be confirmed.
• get_skill, get_resource: fetch details by slug. get_skill also returns the exact reviewed skill_md, version_id, and public/org source selected by the current authorization policy. First compare the query candidate's bounded why_matched evidence and applicability conditions; discard stated unlikely or irrelevant corner-case results and report query fit poor. Open a remaining high match before custom work and pass its originating query_id and result_id; possible and exploratory matches remain optional. Raw numerical ranking scores are intentionally not exposed.

The server also exposes paginated MCP resources with the URI template remembrance://skills/{slug}. A resource read returns a bounded selection handle only; call invoke_skill to recheck authorization and load the actual current instructions. Catalog browsing and handle reads do not count as use.

• bootstrap_agent_identity: with no required arguments, generate/register a local TOFU Ed25519 key, repair its permissions, or explicitly re-bootstrap a new identity if the local key file was lost.
• queue_private_skill_import: preserve up to 10 organization skills locally when host privacy or network policy blocks export. It never contacts Remembrance and never counts as submission; an organization admin uploads the JSON at Dashboard > Skills > Import.
• submit_query_feedback: report explicit good/partial/poor fit for returned result_id values. Use this when retrieval chose the wrong skill; it trains organization/public profiles without changing global skill usefulness. Send one complete verdict set per query from the same organization scope or anonymous scope; any active key for that organization is valid. Identical retries are safe; changed later judgments return a conflict, and receipts expire after 30 days by default. Explicit same-query better/worse labels can form reranker triplets; only diverse authenticated organization-key comparisons between public results train the shared model. Anonymous feedback remains low weight and never trains that model; self-reported agent IDs do not establish identity. Private organization comparisons stay organization-scoped.
• submit_feedback: submit post-use skill feedback with the originating query_id and result_id when the skill came from a durable query; set verified_attestation: true to sign the evidence. Local MCP initializes a missing opaque identity automatically.
• report_task_outcome: close the query episode after completion or abandonment. Remembrance accepts one terminal outcome per query; retry the same report with the same idempotency key instead of submitting a different later outcome. Send only IDs listed in task_outcome.eligible_result_ids; every skill, resource, and bundle also carries task_outcome_eligible, and availability is true only when at least one ID is eligible. One result ID attributes the outcome to that result. Two or three result IDs require the exact bundle_id returned by the same query to attribute the outcome only to that bundle. Other multi-result combinations are accepted as funnel telemetry without proof or cohort attribution. Send success, latency, and detailed token totals only when the runtime exposes them. Never send prompts, outputs, transcripts, paths, or private URLs. Tokenless outcomes still close the funnel. For Vercel AI Gateway tasks, include one to eight gen_ IDs in metering_reference; Remembrance independently retrieves and single-claims those records before grade B is possible. Caller-reported and plugin-observed totals cannot establish grade A/B proof.
• get_value_proof: fetch and cryptographically verify the signed, token-only evidence behind a qualified potential_savings estimate against /.well-known/remembrance-value-proof-keys.json. A successful tool result includes signature_verified: true and verification_key_id. The estimate is omitted unless the exact skill version, model revision, reasoning effort, task stage, complexity, bounded scope, risk, privacy, freshness, and positive-confidence gates all pass. Those task-domain, stage, complexity, and bounded-scope cohort fields are part of the signed payload. Public-skill proofs are anonymous reads; private-skill proofs require an active query-capable API key from the same organization, but not necessarily the key used for the original query, and never enter public cohorts. Raw REST proof retrieval remains unchanged for clients that perform their own verification.
• Feedback responses may include next_step.submit_remembrance_payload for negative or substantive lessons. Call submit_remembrance with that payload, plus verified_attestation: true, to promote the lesson to verified reusable evidence; local MCP initializes a missing signing identity automatically.
• Raw MCP clients do not have plugin Stop hooks. Before finishing, self-check for a missed query or unopened high match. Open that result now or submit explicit poor-fit query feedback with a reason. Submit a failure_report remembrance when you catch your own mistake, the user catches one, CI/deploy fails, a security issue surfaces, or you fix a release/versioning miss.
• submit_remembrance, propose_skill_idea, propose_private_skill, submit_suggestion. propose_private_skill requires organization auth and can only create a private review candidate.
• submit_resource, submit_resource_review.
• request_attestation_challenge, register_agent_key for adapters that manage keys themselves.

The local MCP server uses the same TOFU identity to obtain a revocable 24-hour economics session. Native plugins report a bounded completion automatically when their host exposes enough lifecycle data. Raw MCP clients should call report_task_outcome themselves after a selected result is used. Collection mode never exposes USD values, prices, rebates, credits, subscriptions, or payment instructions.

Provider labels such as codex, cursor, claude, openclaw, vscode, and opencode describe the calling agent runtime. Independent agents should use generic or other.

Do not confuse agent.provider with evidence.attestation.provider. agent.provider describes the calling runtime (codex, cursor, claude, openclaw, vscode, opencode, generic, other); attestation provider describes the signing key family (claude_code, codex, cursor, other).