Skip to main content

​
Overview

Memory tools let the agent recall past conversations, decisions, and preferences stored in memory files. The memory system indexes MEMORY.md, all files under memory/*.md, and recent chat history. Searches use a hybrid approach combining vector similarity (semantic) and full-text search (BM25) for best results.
The memory_search tool description tells the AI it is a “mandatory recall step” - the model is instructed to search memory before answering questions about prior work, dates, people, or preferences.

​
Tools

Semantically search memory files and chat history. Security level: safe | Tier: Standard
​
query
string
required
Natural language search query. Describe what you are looking for, not just keywords.
​
maxResults
number
default:"6"
Maximum results to return (1-20).
​
minScore
number
default:"0.35"
Minimum relevance score threshold (0.0-1.0). Lower values return more results but may include irrelevant matches.
​
source
string
default:"all"
Filter by source: all, memory (files only), chat (conversations only), custom.
{
  "query": "API authentication decisions",
  "maxResults": 5
}
Response format: 
{
  "query": "API authentication decisions",
  "results": [
    {
      "path": "memory/architecture.md",
      "lines": "42-56",
      "text": "Decided to use JWT with 15-minute expiry...",
      "score": 0.87,
      "source": "memory"
    }
  ],
  "totalFound": 3,
  "method": "hybrid",
  "stats": {
    "totalFiles": 12,
    "totalChunks": 847
  }
}

​
memory_get

Read a specific section from a memory file by path and line range. Security level: safe | Tier: Standard
​
path
string
required
Path to the memory file (e.g., memory/decisions.md).
​
lines
string
Line range to read, in the format returned by memory_search (e.g., "42-56").
Use this after memory_search returns a match - read the full context around the matched snippet.

​
memory_stats

Show memory system statistics. Security level: safe | Tier: Standard Returns: total indexed files, total chunks, last indexed timestamp, and available memory sources.

​
Memory File Locations

SourcePathDescription
PrimaryMEMORY.mdMain memory file in project root
Memory dirmemory/*.mdAdditional memory files
ChatInternal DBIndexed conversation history
CustomConfigurableExtra directories via memory.extraPaths

​
Writing to Memory

Memory tools only read - they do not write. To save information to memory, use write_file or edit_file to update MEMORY.md directly: 
write_file(
  path: "MEMORY.md",
  content: "\n## Decision: Auth Strategy\nDecided on JWT with refresh tokens...",
  append: true
)
The memory watcher picks up file changes and re-indexes automatically (debounced at 2 seconds).

​
Memory Isolation

Each conversation operates within an IsolationContext that restricts which memory paths are accessible. In multi-user setups, different users see different memory namespaces. Shared project memory is accessible to all sessions that share a projectId.

File Operations

Read and write memory files directly.

Sessions

Share memory context across spawned sessions.