Agent and registry endpoints.

curl -X POST https://remembrance.dev/api/v1/agent/query \
  -H 'content-type: application/json' \
  -d '{"task":{"domain":"web-ui-qa","summary":"QA a pricing page","constraints":["responsive"]},"limit":3}'

Direct skill catalog

Use the catalog when a person explicitly names a Remembrance skill. Listings contain bounded metadata and a remembrance://skills/{slug}handle, never the private instruction body. The catalog's q parameter is an indexed, normalized slug-prefix filter for resolving a known name or partial slug; it is not relevance search. Use the query endpoint for discovery. Invoke only an exact slug returned by the catalog. Invocation rechecks access and organization policy, resolves the current accepted version, and returns post-use feedback and outcome instructions. It is an explicit selection, so do not send query-fit feedback. MCP clients expose the same flow through list_skills, invoke_skill, and paginated resources.

curl 'https://remembrance.dev/api/v1/agent/skill-catalog?q=mongodb&limit=20'

curl -X POST https://remembrance.dev/api/v1/agent/skill-invocations \
  -H 'content-type: application/json' \
  -H 'idempotency-key: direct-use-001' \
  -d '{"slug":"mongodb-aggregation-optimization","client_context":{"surface":"rest","runtime":"other"}}'

Installation identity and preferences

A shared organization key identifies the tenant. Native plugins and local MCP also create one Ed25519 TOFU installation identity and register a private-safe runtime profile for Codex, Claude Code, Cursor, OpenClaw, VS Code, OpenCode, or another client. Runtime profiles distinguish desktop, CLI, extension, and gateway surfaces without sending hostnames, usernames, config paths, or repository paths. They remain children of one billing principal.

The signed challenge exchange returns a revocable 24-hour principal session. Query, catalog, detail, and invocation reads ignore an unusable session and continue under the API-key or anonymous scope; identity linking and preference writes reject stale sessions. Native clients renew automatically in the background. The legacy economics endpoint and header remain accepted aliases.

Organization members can create a ten-minute, single-use link from Dashboard > Agents > Instances. Once linked, bounded working preferences follow that member across installations, with runtime-specific residuals only when behavior differs. Built-in controls cover common presentation choices; extensible preferences can also describe discretionary workflow and strategy selection. An explicit instruction governs the current task immediately. Known built-ins activate durably at once; custom settings remain pending until automatic normalization and validation approves them. Unsafe or uncertain custom behavior stays inactive and is never replayed. Inferred values require repeated agreement across tasks and days, then expire after 180 inactive days. Query and invocation responses return only task-relevant values; preferences never weaken safety, authorization, privacy, applicability, required skill steps, validation, review, or required organization guidance. Organization admins set guidance under Dashboard > Agents > Preferences as Required or Recommended. The wire field project_key is an opaque project-context hash, not a policy layer.

Retrieval first establishes applicability and a stable match tier. Organization-private compatibility records for the exact skill version may reorder candidates only inside that tier, with original and personalized ranks kept separate. Classification runs asynchronously; query and invocation make no generative preference call, and missing or stale coverage is neutral. Each skill candidate or invocation may include a bounded preference_application that surgically applies discretionary presentation, workflow, or strategy choices and reports replaced defaults or blocked conflicts.

After actual use, submit compatibility feedback only when the result includes a preference_compatibility_feedback offer. Reuse its exact query, result, version, and server-issued preference IDs; Remembrance verifies the correlated fetch and active preference before recording the organization-private observation.

Authenticating with an organization key

Pass the org key on either the x-remembrance-api-key header or as an Authorization: Bearer token. Generate a key on /dashboard/keys. Native hooks and local/bundled MCP servers read the key from ~/.config/remembrance/config.json or REMEMBRANCE_API_KEY. Hosted MCP cannot read local files; it needs the key forwarded on its HTTP request. Raw REST clients also do not load plugin config automatically. See the install & connect guide.

For a custom registry, store apiKey and apiUrl together in the shared config, or bind an environment key with REMEMBRANCE_API_KEY_ORIGIN equal to the exact REMEMBRANCE_API_URL. Remote destinations require HTTPS; only loopback development may use HTTP. A trusted private or link-local self-hosted registry also requires REMEMBRANCE_ALLOW_PRIVATE_REGISTRY=true. Invalid or mismatched settings stop locally before any key is forwarded.

curl -X POST https://remembrance.dev/api/v1/agent/query \
  -H 'content-type: application/json' \
  -H 'x-remembrance-api-key: YOUR_ORG_KEY' \
  -d '{"task":{"domain":"web-ui-qa","summary":"QA a pricing page","constraints":["responsive"]},"limit":3}'

Diagnose the exact transport you plan to use. MCP clients should call run_connection_doctor; it performs a non-mutating catalog read and reports local versus hosted transport, credential source, verified registry scope, and observed native lifecycle components with exact remediation and without returning key material, absolute paths, custom registry URLs, or stable destination fingerprints. Local MCP also reports whether signed contributions are ready and initializes a missing opaque identity automatically. For raw REST, call the endpoint with the same header as the real request. An anonymous browser or curl probe proves only that probe was anonymous. Bundled local MCP, including Codex, reads the same shared config as native hooks. A manual hosted registration cannot read caller files and needs its own request credential. A Codex tenant/privacy-policy denial occurs before Remembrance receives a request and is not a Remembrance rejection. If the MCP tool itself is absent, run npx @remembrance-ai/mcp-server doctor, repair the host registration, restart the host, and rerun the MCP doctor. Use get_connection_status only for the underlying status fields.

curl https://remembrance.dev/api/v1/agent/connection-status \
  -H 'x-remembrance-api-key: YOUR_ORG_KEY'

Organization-private lesson lane

Native organization installs prepare a generalized lesson locally, encrypt the canonical post-redaction record, and use one separately approvable network action. The current policy pins both the supported redaction version and its exact rule digest. Unsupported profiles are rejected with stable unsupported_redaction_version or unsupported_redactor_digest codes; the local encrypted draft becomes terminal and remains on the device until explicitly deleted.

A locally held draft may use the same endpoint and exact host action to report a held_safety_event. That branch carries only event type, held category counts, contract/redactor profile, policy and event digests, idempotency, and a challenge-bound attestation. It never sends lesson prose, conditions, tags, correlation IDs, evidence hashes, candidate digests, paths, or draft content. Signed hold receipts are independently verified by local MCP.

The action, original record, encrypted payload, and signed receipt always remain organization-private and never fall back to anonymous or public submission. The agent cannot request or observe propagation. If an organization admin enables Contribution propagation, a later server-owned step may create a separate, freshly redacted public candidate from an accepted non-preference outcome. That derivative still passes the complete public safety, verification, topology, and review pipeline and is never published directly.

Raw hold events expire after 90 days; content-free daily aggregates and signed receipts remain available for auditing. Hold telemetry is isolated from remembrances, verification, review, topology, and skill materialization. Organization admins can pause the entire lane, and REMEMBRANCE_HEALTH_REPORTING=0 disables this optional client report without affecting querying or retained drafts.

Native clients may submit a degraded activation report using /api/v1/agent/client-health-reports. The strict schema accepts only bounded versions, component states, and issue codes. It rejects prompts, keys, repository paths, source content, raw logs, and arbitrary diagnostic fields. Reports are deduplicated and require independent corroboration; one report is never accepted as a defect automatically.

Public agent endpoints accept anonymous requests as untrusted intake. API keys are optional for public network use, required for org/private payloads and higher-trust enterprise workflows, and invalid keys are always rejected.

An agent host may independently restrict the Remembrance server, destination, or tools. Managed installations should use the exact host-specific allowlists on the install guide. With an organization key, /agent/skill-ideas remains organization-scoped. Never remove or bypass the key to force a public candidate; use the reviewed public-propagation flow after private review.

Organization-key skill reads honor the organization's public-skill access policy. The recommended default combines reviewed public skills with private organization skills, with a same-slug private skill taking precedence. In Organization skills onlymode, public skills are absent from skill list, detail, lexical, and vector-query results; private skills and public resources remain available. Admins can still browse the dashboard catalog to create a connected or detached private clone. Connected public updates are notices only until an admin applies an unchanged update or sends a diverged update through organization review. An admin can freeze any private skill's evolution from the skill workbench; candidates remain reviewable, but content, metadata, active-version changes, and repair replay stay blocked until evolution resumes. Safety quarantine remains available.

Every agent query response includes the effective policy in skill_access. Native plugins, MCP instructions, and the Remembrancer skill disable bundled and live public-skill fallbacks under organization-only mode. With an organization key configured, an unavailable query also fails closed for public-skill fallback because the current policy cannot be confirmed.

Recognized outdated or legacy versionless Remembrance plugin and MCP requests may also receive an optional client_update object. The same bounded notice is placed first in contribution_directive.message so clients released before startup update checks existed can still tell the user. The API returns no executable update command; use only the host UI or instructions bundled with the installed client, then restart or reload that host. Unrelated REST callers are not classified as Remembrance clients.

Organization metadata_update suggestions use explicit array semantics. A field named in changed_fields is an exact replacement, including an empty array; an absent array remains unchanged. Advanced clients may set array_update_modes to choose merge or replace for each supported array. Accepted catalog metadata and managed SKILL.md frontmatter activate atomically. Metadata-only updates preserve instruction-body bytes, and organization admins can inspect field-level version diffs and create an audited rollback from version history.

Query responses include an opaque result_id, a stable match_tier, a concise reason, and approximate context tokens when known. Each candidate's why_matched shows bounded matched terms and capabilities, satisfied and missed constraints, exact-domain agreement, and qualitative lexical and semantic evidence from the same inputs used by retrieval; unstable raw scores stay internal. applicability separately shows likely, conditional, unlikely, or unknown fit; general, specialized, or corner-case scope; and declared use and exclusion conditions. Unknown does not mean generally applicable. Bounded tags, capabilities, required permissions, dependencies, and contraindications help callers reject an irrelevant or unsafe detour without opening every result. Open a remaining high match before custom work with get_skill or get_resource, passing the originating query and result IDs. get_skillreturns the exact active reviewed skill_md, version ID, and public or organization source; possible and exploratory matches remain optional. Known-inapplicable results are never high, and conditional results are not imperative. Report superficially related or irrelevant corner-case results as poor in one complete verdict set of explicit good, partial, and poor query matches to /api/v1/agent/query-feedback; use /api/v1/agent/feedback only after actually using a skill. Pass the same IDs with post-use feedback to close the surfaced, opened, query-rated, used, and useful funnel. A surfaced result that is never opened remains aggregate diagnostic evidence only and is not treated as implicit negative feedback. Use the same organization scope or anonymous scope as the original query; any active key for that organization is valid. Query receipts expire after 30 days by default. Identical retries are idempotent, but later changed or appended judgments return 409, so leave uncertain results unrated and submit once. Explicit better/worse labels from the same query can form preference triplets. Diverse authenticated organization-key comparisons between public results train the shared reranker; anonymous feedback remains low weight and cannot train that model or directly affect organization rankings. Self-reported agent IDs never count as identities. Private org comparisons remain org-scoped, broad domain profiles require stronger support than exact-query profiles, and ranking adjustments are bounded. Fresh-feedback shadow evaluation, activation, and rollback are automatic. Skill embeddings stay content-derived; feedback reranks the retrieved candidate pool instead of rewriting vectors. Organization receipts retain an intent hash and bounded domain, not the raw task summary or constraints.

curl -X POST https://remembrance.dev/api/v1/agent/query-feedback \
  -H 'content-type: application/json' \
  -H 'idempotency-key: QUERY_ID:fit-v1' \
  -d '{"query_id":"rq_...","overall_fit":"partial","results":[{"result_id":"qres_...","fit":"good"},{"result_id":"qres_...","fit":"poor","reasons":["wrong_task"]}]}'

Native plugins create an opaque directive_id when they explicitly ask an agent to query. They post a shown event to /api/v1/agent/directive-events; the subsequent query carries that ID in client_context or the completed-tool hook reports it as followed. Fresh directives stay pending and are excluded from the compliance denominator until the bounded follow window closes. This telemetry is redacted, TTL-bound, fail-open, and never affects identity, trust, or ranking.

Optional token-savings proof

A query may include a compact potential_savings estimate only for a high, accepted, current, non-high-risk match with fresh grade A/B proof for the exact skill version, model revision, and reasoning effort in the same task-stage, complexity, and bounded-scope cohort. The lower 90% confidence bound and median saved-token estimate must be positive, and privacy thresholds must pass. The field is omitted when any gate fails;estimated_tokens remains the skill context size and is not itself a savings claim. Fetch the signed token-only receipt from/api/v1/value-proofs/[id] and verify it with the public key set. Public-skill proofs are anonymous reads. A private-skill proof requires an active query-capable API key from the same organization; it need not be the key used for the original query. It remains isolated to that workspace and is never publicly cached. The local and hosted MCP proof tools verify Ed25519 before returning the receipt; raw REST clients verify against the published public-key set. Collection mode exposes no prices, rebates, credits, subscription details, payment methods, or other monetary fields.

Every returned skill, resource, and bundle includes task_outcome_eligible. Close the episode at /api/v1/agent/task-outcomes using only the exact IDs in task_outcome.eligible_result_ids; availability is true only when that list is nonempty. Each query accepts one terminal outcome; retry the same report with the same idempotency key instead of submitting a different later outcome. An organization admin can disable private measurement without disabling eligible public-result telemetry. Completion without token counts still improves funnel telemetry. Send detailed tokens only when the runtime exposes them, and never send prompts, transcripts, outputs, source paths, private URLs, or proprietary task content. An estimate ID is retained only when its active proof matches the exact selected versions and scope; a stale or unrelated ID is dropped without discarding the completion outcome. For Vercel AI Gateway tasks, include an explicit metering reference with every generation ID used by the task. Remembrance encrypts the references, retrieves usage independently, and claims each generation once; caller-provided totals and labels remain modeled evidence until that reconciliation succeeds. Controlled paired evaluations can support grade A proof, and reconciled Vercel Gateway metering can support grade B proof; plugin-observed and agent-reported totals remain modeled evidence only.

Raw MCP and REST clients do not have plugin Stop hooks. Before acting on short follow-ups, agents should infer the task from the full conversation and query with a redacted summary. Before finishing, they should self-check for a missed query and submit a redacted failure_report for reusable self-corrections, user-caught mistakes, CI/deploy failures, security issues, or release misses.