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: 
ironclaw memory search <QUERY> [OPTIONS]
​
query
string
required
Search query. Can be keywords, questions, or natural language.
​
-l, --limit
integer
default:"5"
Maximum number of results to return.
Examples: 
ironclaw memory search "meeting notes from last week"
ironclaw memory search "TODO" --limit 10
ironclaw memory search "what did I discuss about the project?"
Output: 
Found 3 result(s) for "meeting notes from last week":

1. [=====>] (score: 0.847)
   notes/meetings/2024-03-01-standup.md
   
   # Team Standup - March 1, 2024
   
   ## Attendees
   - Alice, Bob, Charlie
   
   ## Discussion
   - Reviewed sprint progress
   - Discussed blockers on authentication feature...

2. [====>] (score: 0.623)
   daily/2024-02-28.md
   
   Prepared agenda for tomorrow's meeting. Need to discuss:
   - API rate limiting
   - Database migration strategy
   - Testing coverage...

3. [===>] (score: 0.412)
   HEARTBEAT.md
   
   Last updated: 2024-03-01
   Recent activities:
   - Attended team standup
   - Code review for PR #42...
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: 
ironclaw memory read <PATH>
​
path
string
required
File path in the workspace (e.g., “MEMORY.md”, “daily/2024-01-15.md”).
Examples: 
ironclaw memory read MEMORY.md
ironclaw memory read notes/project-ideas.md
ironclaw memory read daily/2024-03-01.md
Output: 
# Core Memory

Key facts and information the agent should always remember.

## User Profile
- Name: Alice
- Timezone: America/New_York
- Preferences: Concise summaries, technical details

## Active Projects
1. Website redesign (due March 15)
2. API v2 migration (in progress)
3. Documentation updates (ongoing)

## Important Contacts
- Bob (teammate): [email protected]
- Charlie (manager): [email protected]
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: 
ironclaw memory write <PATH> [CONTENT] [OPTIONS]
​
path
string
required
File path to write (e.g., “notes/idea.md”).
​
content
string
Content to write. If omitted, reads from stdin.
​
-a, --append
flag
Append to the file instead of overwriting.
Examples: 
# Write from command line
ironclaw memory write notes/quick-note.md "Remember to follow up on that email"

# Write from stdin
echo "# New Note\n\nSome content here" | ironclaw memory write notes/new.md

# Append to existing file
ironclaw memory write daily/2024-03-01.md "\n- Completed PR review" --append

# Write multi-line content
ironclaw memory write notes/todo.md "$(cat <<EOF
# TODO List

- [ ] Finish documentation
- [ ] Review PR #42
- [ ] Update dependencies
EOF
)"
Output: 
Wrote to notes/quick-note.md
or 
Appended to daily/2024-03-01.md
Writing without --append will overwrite the entire file. Use append mode to add content to existing files.

​
tree

Show workspace directory structure: 
ironclaw memory tree [PATH] [OPTIONS]
​
path
string
default:""
Root path to start from. Defaults to workspace root.
​
-d, --depth
integer
default:"3"
Maximum depth to traverse.
Examples: 
ironclaw memory tree
ironclaw memory tree notes
ironclaw memory tree --depth 2
Output: 
./
├── MEMORY.md
├── IDENTITY.md
├── HEARTBEAT.md
├── USER.md
├── AGENTS.md
├── SOUL.md
├── daily/
│   ├── 2024-02-28.md
│   ├── 2024-03-01.md
│   └── 2024-03-04.md
├── notes/
│   ├── project-ideas.md
│   ├── quick-note.md
│   └── meetings/
│       ├── 2024-03-01-standup.md
│       └── 2024-02-26-planning.md
└── code/
    ├── snippets.md
    └── examples/
        ├── api-usage.md
        └── config-examples.md

​
status

Show workspace status and health: 
ironclaw memory status
Output: 
Workspace Status
  User:        default
  Files:       42
  Directories: 8

  Identity files:
    [+] MEMORY.md
    [+] HEARTBEAT.md
    [+] IDENTITY.md
    [+] SOUL.md
    [+] AGENTS.md
    [+] USER.md
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: 
~/.ironclaw/workspace/
├── MEMORY.md           # Core facts and memory
├── IDENTITY.md         # Agent personality and traits
├── HEARTBEAT.md        # Activity log and reflections
├── USER.md             # User profile and preferences
├── AGENTS.md           # Instructions for AI agents
├── SOUL.md             # Long-term goals and values
├── daily/              # Daily notes and journals
│   └── YYYY-MM-DD.md
├── notes/              # General notes
│   ├── meetings/
│   ├── ideas/
│   └── ...md
├── code/               # Code snippets and examples
└── ...                 # Custom directories

​
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

ironclaw memory write daily/$(date +%Y-%m-%d).md "$(cat <<EOF
# $(date +%Y-%m-%d)

## Accomplishments
- Completed feature X
- Fixed bug Y

## Notes
- Meeting with Bob about project Z

## Tomorrow
- [ ] Review PR #42
- [ ] Update docs
EOF
)"

​
Search for TODO items

ironclaw memory search "TODO" --limit 20

​
Backup all notes

ironclaw memory read notes/important.md > backup.md

​
Check what the agent remembers

ironclaw memory read MEMORY.md

​
Append to activity log

ironclaw memory write HEARTBEAT.md "\n- $(date): Deployed new version" --append

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us