Memory & Workspace

Persistent memory operations for workspace storage

Overview

Memory tools provide access to persistent, database-backed workspace storage. This is separate from the local filesystem and designed for agent memory, decisions, context, and long-term knowledge.

Use memory_* tools for workspace storage (HEARTBEAT.md, MEMORY.md, daily logs, etc.). Use read_file/write_file for local filesystem operations.

Tools

memory_search

Search past memories, decisions, and context using hybrid search (full-text + semantic). Returns relevant snippets with relevance scores.

MUST be called before answering questions about prior work, decisions, dates, people, preferences, or todos.

Input Parameters

query · string · required

The search query. Use natural language to describe what you’re looking for.

limit · integer · default: 5

Maximum number of results to return (min: 1, max: 20)

Output

query · string

The original search query

results · array

Array of search results with content, score, document ID, and match type

result_count · integer

Number of results returned

Result Object

content · string

Relevant snippet from the document

score · number

Relevance score (higher is more relevant)

document_id · string

UUID of the source document

is_hybrid_match · boolean

True if both full-text and semantic search matched

Example

{
  "query": "What did we decide about the API design?",
  "limit": 5
}

Response

{
  "query": "What did we decide about the API design?",
  "results": [
    {
      "content": "Decided to use REST API with JSON responses. Authentication via API keys.",
      "score": 0.89,
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "is_hybrid_match": true
    }
  ],
  "result_count": 1
}

---

memory_write

Write to persistent memory (database-backed storage). Use for important facts, decisions, preferences, or lessons learned that should be remembered across sessions.

Input Parameters

content · string · required

The content to write to memory. Be concise but include relevant context.

target · string · default: "daily_log"

Where to write:

• memory - MEMORY.md (curated long-term facts)
• daily_log - today’s timestamped log
• heartbeat - HEARTBEAT.md checklist
• Custom path like projects/alpha/notes.md

append · boolean · default: true

If true, append to existing content. If false, replace entirely.

Output

status · string

Always “written” on success

path · string

Path where content was written

append · boolean

Whether content was appended (true) or replaced (false)

content_length · integer

Number of bytes written

Example

{
  "content": "Completed API authentication implementation. Using JWT tokens.",
  "target": "memory",
  "append": true
}

Response

{
  "status": "written",
  "path": "MEMORY.md",
  "append": true,
  "content_length": 68
}

Protected Files

The following identity files cannot be written via tools (prompt injection defense):

• IDENTITY.md
• SOUL.md
• AGENTS.md
• USER.md

Constraints

• Content cannot be empty
• Rate limited: 20 calls per minute, 200 per hour
• Identity files are protected from modification

---

memory_read

Read a file from workspace memory (database-backed storage). Use this to read files shown by memory_tree.

Input Parameters

path · string · required

Path to the file (e.g., MEMORY.md, daily/2024-01-15.md, projects/alpha/notes.md)

Output

path · string

Path to the file that was read

content · string

File content

word_count · integer

Number of words in the content

updated_at · string

RFC3339 timestamp of last update

Example

{
  "path": "MEMORY.md"
}

Response

{
  "path": "MEMORY.md",
  "content": "# Project Memory\n\nCompleted API auth...",
  "word_count": 247,
  "updated_at": "2024-01-15T10:30:00Z"
}

Error Conditions

• ExecutionFailed: File not found or read failed

---

memory_tree

View the workspace memory structure as a tree. Returns a hierarchical view of files and directories.

The workspace is separate from the local filesystem. Use memory_read to read files shown here, not read_file.

Input Parameters

path · string · default: ""

Root path to start from (empty string for workspace root)

depth · integer · default: 1

Maximum depth to traverse (1 = immediate children only, max: 10)

Output

Returns a JSON array representing the tree structure. Directories end with / and may have children.

Example

{
  "path": "",
  "depth": 2
}

Response

[
  "MEMORY.md",
  "HEARTBEAT.md",
  "README.md",
  {
    "daily/": [
      "2024-01-15.md",
      "2024-01-14.md"
    ]
  },
  {
    "projects/": [
      "alpha/",
      "beta/"
    ]
  }
]

Constraints

• Maximum depth: 10 levels
• Directories shown with trailing /
• Files shown without trailing slash
• Empty directories shown as simple strings

Use Cases

Daily Logging

Automatic timestamped session notes:

{
  "content": "Fixed bug in authentication flow. Added unit tests.",
  "target": "daily_log"
}

Long-term Memory

Curated facts and decisions:

{
  "content": "API uses JWT tokens. Tokens expire after 1 hour.",
  "target": "memory"
}

Project Notes

Organized by project:

{
  "content": "Architecture: microservices with event bus",
  "target": "projects/alpha/architecture.md",
  "append": false
}

Searching Context

Before answering questions:

{
  "query": "What authentication method are we using?",
  "limit": 3
}