Agent Memory

Persistent semantic memory for individual agents. Store facts, decisions, and preferences with evidence links, lifecycle controls, and automatic relevance-based recall.

Overview

Agent Memory enables your AI agents to persist information across sessions. Unlike conversation history (which is ephemeral), memories are stored server-side and can be recalled semantically based on relevance to the current context.

Key Features

• Semantic Storage — Memories are embedded for similarity search
• Source-Linked Evidence — Attach docs, chunks, PRs, issues, and URLs to critical memories
• Lifecycle Controls — Invalidate or supersede stale memories without losing history
• Verification — Re-check whether a memory is still backed by valid evidence
• Confidence Decay — Memories lose relevance over time unless reinforced
• Type Classification — Categorize as facts, preferences, decisions, etc.
• TTL Support — Set expiration times for temporary memories
• Metadata Filtering — Filter recalls by type, category, or custom tags

MCP Tools

rlm_remember

Store a new memory with optional metadata.

rlm_remember({

  text: "User prefers dark mode in all applications",

  type: "preference",

  category: "ui",

  scope: "project",

  ttl_days: null  // null = permanent

})

Parameters

rlm_remember_bulk

Store multiple memories in a single call for efficient batch operations.

rlm_remember_bulk({

  memories: [

    { text: "User prefers TypeScript", type: "preference" },

    { text: "API uses JWT auth", type: "fact", category: "auth" },

    { text: "Deploy to staging first", type: "decision", ttl_days: 30 }

  ]

})

Parameters

Response

{

  "stored": 3,

  "memory_ids": ["mem_abc", "mem_def", "mem_ghi"],

  "message": "Stored 3 memories"

}

rlm_recall

Retrieve memories relevant to a query using semantic search.

rlm_recall({

  query: "What are the user's UI preferences?",

  limit: 5,

  type: "preference",

  min_relevance: 0.5

})

Parameters

Response

{

  "memories": [

    {

      "id": "mem_abc123",

      "content": "User prefers dark mode in all applications",

      "type": "preference",

      "category": "ui",

      "confidence": 0.92,

      "relevance": 0.87,

      "createdAt": "2025-01-20T10:30:00Z",

      "lastAccessedAt": "2025-01-23T14:15:00Z",

      "status": "ACTIVE",

      "freshness": "fresh",

      "evidence_count": 2

    }

  ],

  "total": 1

}

rlm_memories

List all memories with optional filters (no semantic search).

rlm_memories({

  type: "decision",

  limit: 20,

  offset: 0

})

rlm_forget

Delete specific memories by ID or filter.

// Delete by ID

rlm_forget({ memory_id: "mem_abc123" })

// Delete all memories of a type

rlm_forget({ type: "todo" })

Memory Lifecycle Tools

Use Memory V2 lifecycle tools when you need memory that can be traced back to evidence and updated safely over time instead of being hard-deleted.

rlm_memory_attach_source

Attach evidence to a memory, such as a document chunk, PR, issue, commit, or URL.

rlm_memory_attach_source({

  memory_id: "mem_abc123",

  evidence_type: "CHUNK",

  chunk_id: "chunk_456",

  snippet: "OAuth callback validates state before token exchange",

  weight: 1.0

})

Use this for fact, decision, and learning memories that should stay grounded in project evidence.

rlm_get_chunk

Retrieve the full content for a referenced chunk when you need to inspect the exact source behind a memory or a query result.

rlm_get_chunk({

  chunk_id: "chunk_456"

})

rlm_memory_verify

Verify whether a memory still has valid supporting evidence.

rlm_memory_verify({

  memory_id: "mem_abc123",

  mark_stale_if_missing: true

})

{

  "memory_id": "mem_v2_abc123",

  "verified": true,

  "total_evidence": 2,

  "valid_evidence": 2,

  "invalid_evidence": 0,

  "evidence_score": 1.0,

  "status": "ACTIVE"

}

rlm_memory_invalidate

Mark a memory as invalid when it is no longer true. This preserves the audit trail better than deleting it outright.

rlm_memory_invalidate({

  memory_id: "mem_abc123",

  invalidated_at: "2026-04-10T14:30:00Z",

  reason: "Legacy OAuth flow replaced by PKCE-only flow"

})

rlm_memory_supersede

Replace an outdated memory with a newer one while keeping the relationship explicit.

rlm_memory_supersede({

  old_memory_id: "mem_old_auth",

  new_memory_id: "mem_new_auth",

  reason: "Authorization server configuration changed"

})

Decision Log Tools

Use decision tools when a memory is not enough and you need a structured, ADR-style record with rationale, alternatives, and a supersession chain.

rlm_decision_create

Create a formal technical or architectural decision record.

rlm_decision_create({

  title: "Use Redis for background job deduplication",

  owner: "platform-team",

  scope: "backend",

  impact: "HIGH",

  context: "Workers need a shared dedupe layer across deploys",

  decision: "Adopt Redis SETNX-based deduplication",

  rationale: "Faster operational rollout than queue-layer rewrite",

  alternatives: ["Postgres advisory locks", "Kafka compaction"],

  tags: ["jobs", "reliability", "redis"]

})

rlm_decision_query

Search decisions by free text, scope, impact, status, or tags.

rlm_decision_query({

  query: "redis deduplication",

  scope: "backend",

  impact: "HIGH",

  include_superseded: false,

  limit: 10

})

rlm_decision_supersede

Replace an existing decision with a new one while preserving the evolution chain between both records.

rlm_decision_supersede({

  old_decision_id: "DEC-014",

  title: "Move job deduplication to queue middleware",

  owner: "platform-team",

  scope: "backend",

  impact: "HIGH",

  context: "Redis hot key pressure increased with traffic growth",

  decision: "Shift deduplication into queue middleware",

  rationale: "Reduces operational hotspots and centralizes policy"

})

Confidence Decay

Memories naturally lose confidence over time unless they are accessed or reinforced. This prevents stale information from dominating recalls.

Confidence Decay Formula

new_confidence = base_confidence * (decay_rate ^ days_since_access)

Example: 0.9 confidence, 0.98 decay rate, 7 days

0.9 * (0.98 ^ 7) = 0.77

Reinforcement

When a memory is accessed via rlm_recall, its confidence is boosted slightly. Storing the same content again also reinforces the memory.

Memory Types

Best Practices

Guidelines

• Be specific — "User prefers tabs over spaces" not "User has code style preferences"
• Use appropriate types — Helps with filtering and organization
• Set TTL for temporary info — Prevent memory bloat
• Attach evidence for critical memories — Facts and decisions should be verifiable
• Invalidate or supersede stale knowledge — Keep history instead of deleting everything
• Let confidence decay work — Don't manually set confidence to 1.0
• Recall before storing — Check if similar memory exists to reinforce instead

Plan Limits

Next Steps