MCP Tool: remember

Capture durable context from planning, ideation, building, or any domain. remember stores verbatim raw memory as provenance and creates a graph entity in one call.

Overview

Use remember aggressively during agent work to capture decisions, plans, ideas, claims, procedures, artifacts, sessions, and domain facts. It is the capture companion to context: context retrieves what matters, remember stores what future agents should not have to relearn.

Each call does two things:

1. Stores the content verbatim as a raw memory record (provenance, scoped, audited).
2. Creates a corresponding graph entity of the requested kind so the memory is searchable.

Compared to add, remember additionally writes the raw memory record, applies a memory scope, and can auto-link to the active task.

Input Schema

interface RememberInput {
  // Required
  title: string; // Short title
  content: string; // Full content to remember verbatim

  // Memory Configuration
  kind?: MemoryKind; // Memory kind (default "episode")
  domain?: string; // Domain/category
  project?: string; // Project ID (sets project memory scope)
  tags?: string[]; // Searchable tags

  // Linking
  related_to?: string[]; // Entity IDs to link
  task_ids?: string[]; // Task IDs for exact task context
  active_task?: boolean; // Link to the single active doing task (default true)

  // Metadata
  metadata?: Record<string, any>; // Additional structured metadata
}

Memory Kinds

episode, decision, plan, idea, claim, artifact, procedure, domain, session, pattern, rule

Kind	Capture For
episode	Temporal knowledge, learnings (default)
decision	A chosen direction with rationale
plan	Strategy, sequencing, milestones
idea	A brainstormed concept or unresolved option
claim	An atomic fact or assertion
artifact	A file, object, document, asset, or work product
procedure	A repeatable workflow or runbook
domain	A modeled problem space
session	A conversation or work-session checkpoint
pattern	A reusable pattern or best practice
rule	A rule or guideline

Memory Scope

The scope is derived from project:

• With a project, the memory is scoped to that project (project scope).
• Without a project, the memory is private to the calling user (private scope).

Project-scoped writes require access to the project. Project-scoped credentials (an API key bound to specific projects) must supply a project.

Active Task Linking

When active_task is true (default) and a project is supplied, remember looks up the single task in doing status for that project. If exactly one exists, the new memory is linked to it. This keeps captures attached to the work in progress without the caller tracking task IDs.

Supply task_ids for explicit task linkage regardless of the active-task lookup.

Response Schema

interface RememberResponse {
  success: boolean;
  id: string | null; // Created graph entity ID
  message: string;
  timestamp: string;
  conflicts: ConflictWarning[];
  raw_memory_id: string; // Raw memory record ID
  raw_source_id: string; // Raw memory source ID (provenance key)
  policy_reason: string; // Memory policy decision reason
}

Usage Examples

Remember a Decision

{
  "name": "remember",
  "arguments": {
    "title": "Use PKCE for the SPA OAuth flow",
    "content": "Decided to use the Authorization Code flow with PKCE for the single-page app. Implicit flow is deprecated and exposes tokens in the URL fragment. PKCE works without a client secret.",
    "kind": "decision",
    "project": "proj_abc123",
    "domain": "authentication",
    "tags": ["oauth", "security"]
  }
}

Remember a Plan

{
  "name": "remember",
  "arguments": {
    "title": "Crawler import adapter rollout",
    "content": "Step 1: ship the mbox adapter behind a flag. Step 2: add resumable import jobs. Step 3: expose the adapter contract for third-party adapters.",
    "kind": "plan",
    "project": "proj_abc123"
  }
}

Remember a Claim with Explicit Task Context

{
  "name": "remember",
  "arguments": {
    "title": "SurrealDB driver serializes websocket queries",
    "content": "The SurrealDB driver serializes all websocket queries through a per-client asyncio lock. A single driver instance cannot be safely shared across orgs; use driver.clone(group_id).",
    "kind": "claim",
    "project": "proj_abc123",
    "task_ids": ["task_xyz789"]
  }
}

Private Memory (No Project)

{
  "name": "remember",
  "arguments": {
    "title": "Personal note on the rebase workflow",
    "content": "Rebasing the docs branch onto main was clean after stashing the contexts directory.",
    "kind": "episode"
  }
}

Without a project, the memory is private to the calling user.

Notes

• The raw memory record is stored verbatim before the graph entity is created. The raw_source_id is the stable provenance key for that record.
• remember requires a user context. API keys without a resolvable user cannot capture raw source material.
• Every call is authorized against the memory policy and audited.

Error Handling

Error	Cause	Resolution
Organization context required	No org-scoped token	Authenticate with an org-scoped token
User context required to remember raw source material	Credential has no resolvable user	Use a user-bound token or API key
Project is required when MCP credentials are project-scoped	Project-scoped key with no project	Supply a project
api_key_memory_space_denied	API key lacks the memory scope being written	Grant the key the required memory scope

Related

• mcp-reflect.md - Reflect raw notes into reviewable candidates
• mcp-context.md - Retrieve durable memory for a goal
• mcp-add.md - Create a graph entity without raw provenance
• rest-memory.md - REST memory endpoints (/api/memory/raw)