> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## Tools

### memory\_search

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

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

**Input Parameters**

<ParamField path="query" type="string" required>
  The search query. Use natural language to describe what you're looking for.
</ParamField>

<ParamField path="limit" type="integer" default={5}>
  Maximum number of results to return (min: 1, max: 20)
</ParamField>

**Output**

<ResponseField name="query" type="string">
  The original search query
</ResponseField>

<ResponseField name="results" type="array">
  Array of search results with content, score, document ID, and match type
</ResponseField>

<ResponseField name="result_count" type="integer">
  Number of results returned
</ResponseField>

**Result Object**

<ResponseField name="content" type="string">
  Relevant snippet from the document
</ResponseField>

<ResponseField name="score" type="number">
  Relevance score (higher is more relevant)
</ResponseField>

<ResponseField name="document_id" type="string">
  UUID of the source document
</ResponseField>

<ResponseField name="is_hybrid_match" type="boolean">
  True if both full-text and semantic search matched
</ResponseField>

**Example**

```json theme={null}
{
  "query": "What did we decide about the API design?",
  "limit": 5
}
```

**Response**

```json theme={null}
{
  "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**

<ParamField path="content" type="string" required>
  The content to write to memory. Be concise but include relevant context.
</ParamField>

<ParamField path="target" type="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`
</ParamField>

<ParamField path="append" type="boolean" default={true}>
  If true, append to existing content. If false, replace entirely.
</ParamField>

**Output**

<ResponseField name="status" type="string">
  Always "written" on success
</ResponseField>

<ResponseField name="path" type="string">
  Path where content was written
</ResponseField>

<ResponseField name="append" type="boolean">
  Whether content was appended (true) or replaced (false)
</ResponseField>

<ResponseField name="content_length" type="integer">
  Number of bytes written
</ResponseField>

**Example**

```json theme={null}
{
  "content": "Completed API authentication implementation. Using JWT tokens.",
  "target": "memory",
  "append": true
}
```

**Response**

```json theme={null}
{
  "status": "written",
  "path": "MEMORY.md",
  "append": true,
  "content_length": 68
}
```

**Protected Files**

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

  * IDENTITY.md
  * SOUL.md
  * AGENTS.md
  * USER.md
</Warning>

**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**

<ParamField path="path" type="string" required>
  Path to the file (e.g., `MEMORY.md`, `daily/2024-01-15.md`, `projects/alpha/notes.md`)
</ParamField>

**Output**

<ResponseField name="path" type="string">
  Path to the file that was read
</ResponseField>

<ResponseField name="content" type="string">
  File content
</ResponseField>

<ResponseField name="word_count" type="integer">
  Number of words in the content
</ResponseField>

<ResponseField name="updated_at" type="string">
  RFC3339 timestamp of last update
</ResponseField>

**Example**

```json theme={null}
{
  "path": "MEMORY.md"
}
```

**Response**

```json theme={null}
{
  "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.

<Note>
  The workspace is separate from the local filesystem. Use `memory_read` to read files shown here, not `read_file`.
</Note>

**Input Parameters**

<ParamField path="path" type="string" default="">
  Root path to start from (empty string for workspace root)
</ParamField>

<ParamField path="depth" type="integer" default={1}>
  Maximum depth to traverse (1 = immediate children only, max: 10)
</ParamField>

**Output**

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

**Example**

```json theme={null}
{
  "path": "",
  "depth": 2
}
```

**Response**

```json theme={null}
[
  "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:

```json theme={null}
{
  "content": "Fixed bug in authentication flow. Added unit tests.",
  "target": "daily_log"
}
```

### Long-term Memory

Curated facts and decisions:

```json theme={null}
{
  "content": "API uses JWT tokens. Tokens expire after 1 hour.",
  "target": "memory"
}
```

### Project Notes

Organized by project:

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

### Searching Context

Before answering questions:

```json theme={null}
{
  "query": "What authentication method are we using?",
  "limit": 3
}
```