Skip to main content

Overview

The ironclaw memory command provides direct access to the workspace memory system without starting the full agent. Use it to search, read, write, and organize documents in the agent’s workspace.
The workspace is a virtual file system where the agent stores notes, conversation history, user data, and identity files.

Subcommands

Search workspace memory using hybrid full-text and semantic search:
string
required
Search query. Can be keywords, questions, or natural language.
integer
default:"5"
Maximum number of results to return.
Examples:
Output:
Score indicators:
  • =====> - Very relevant (score > 0.8)
  • ====> - Relevant (score > 0.5)
  • ===> - Somewhat relevant (score > 0.3)
  • ==> - Low relevance (score > 0.1)
  • => - Minimal relevance (score ≤ 0.1)

read

Read a file from the workspace:
string
required
File path in the workspace (e.g., “MEMORY.md”, “daily/2024-01-15.md”).
Examples:
Output:
If the file doesn’t exist, you’ll get an error: File not found: notes/missing.md

write

Write or append content to a workspace file:
string
required
File path to write (e.g., “notes/idea.md”).
string
Content to write. If omitted, reads from stdin.
flag
Append to the file instead of overwriting.
Examples:
Output:
or
Writing without --append will overwrite the entire file. Use append mode to add content to existing files.

tree

Show workspace directory structure:
string
default:""
Root path to start from. Defaults to workspace root.
integer
default:"3"
Maximum depth to traverse.
Examples:
Output:

status

Show workspace status and health:
Output:
Legend:
  • [+] - File exists
  • [-] - File missing
Identity files are special documents that define the agent’s personality, goals, and memory. Missing files will be created automatically when the agent runs.

Workspace Structure

The workspace follows a recommended structure:

Search Modes

The search command uses hybrid search combining:
  1. Full-text search: Exact keyword matching with BM25 scoring
  2. Semantic search: Meaning-based matching using embeddings (if enabled)
Results are ranked by combined relevance score.
To enable semantic search, set embeddings.enabled = true in your config and provide an OPENAI_API_KEY.

Examples

Create a daily journal entry

Search for TODO items

Backup all notes

Check what the agent remembers

Append to activity log

Database Backend

Workspace data is stored in your configured database:
  • PostgreSQL: workspace_documents table with full-text search and pgvector for embeddings
  • libSQL/Turso: workspace_documents table with FTS5 full-text index
Search indexes are created automatically on first use.

ironclaw run

Start the agent with full workspace access

ironclaw status

View workspace status