Skip to main content

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.

​
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

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
}

Build docs developers (and LLMs) love

Get started for freeTalk to us