Overview
Theironclaw 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
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.
=====>- 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”).
If the file doesn’t exist, you’ll get an error:
File not found: notes/missing.mdwrite
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.
tree
Show workspace directory structure:string
default:""
Root path to start from. Defaults to workspace root.
integer
default:"3"
Maximum depth to traverse.
status
Show workspace status and health:[+]- 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:- Full-text search: Exact keyword matching with BM25 scoring
- Semantic search: Meaning-based matching using embeddings (if enabled)
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_documentstable with full-text search and pgvector for embeddings - libSQL/Turso:
workspace_documentstable with FTS5 full-text index
Related Commands
ironclaw run
Start the agent with full workspace access
ironclaw status
View workspace status
