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.
ironclaw memory
Query and manage the workspace memory system. The workspace provides persistent storage for documents, notes, and context that the agent can access during conversations.
Subcommands
search - Search workspace memory (hybrid full-text + semantic)read - Read a file from the workspacewrite - Write content to a workspace filetree - Show workspace directory treestatus - Show workspace status and statistics
ironclaw memory search
Search workspace memory using hybrid full-text and semantic search.
Syntax
ironclaw memory search <QUERY> [FLAGS]
Arguments
<QUERY>
Search query string.
Flags
--limit, -l <NUMBER>
Maximum number of results to return.
Examples
# Search for documents about deployment
ironclaw memory search "deployment"
# Search with custom limit
ironclaw memory search "API documentation" --limit 10
# Search for meeting notes
ironclaw memory search "meeting notes Q4"
Output
Found 3 result(s) for "deployment":
1. [=====>] (score: 0.847)
# Deployment Guide
## Prerequisites
Before deploying, ensure you have:
- Docker installed
- Database credentials
- Environment variables configured...
2. [====>] (score: 0.623)
# CI/CD Pipeline
Our deployment pipeline uses GitHub Actions...
3. [===>] (score: 0.412)
# Infrastructure Notes
Deployment targets:
- Production: AWS ECS
- Staging: Heroku...
=====> - Very relevant (score > 0.8)====> - Relevant (score > 0.5)===> - Somewhat relevant (score > 0.3)==> - Marginally relevant (score > 0.1)=> - Low relevance (score ≤ 0.1)
ironclaw memory read
Read a file from the workspace.
Syntax
ironclaw memory read <PATH>
Arguments
<PATH>
File path relative to workspace root (e.g., MEMORY.md, daily/2024-01-15.md).
Examples
# Read the main memory file
ironclaw memory read MEMORY.md
# Read identity file
ironclaw memory read IDENTITY.md
# Read a daily note
ironclaw memory read daily/2024-01-15.md
# Read a nested file
ironclaw memory read projects/website/notes.md
Output
The file content is printed to stdout:
# Memory
Core facts and context about the user:
- Name: Alice
- Role: Software Engineer
- Current project: Building AI assistant
- Preferred language: Python
...
Error Handling
ironclaw memory read nonexistent.md
# Error: File not found: nonexistent.md
ironclaw memory write
Write content to a workspace file.
Syntax
ironclaw memory write <PATH> [CONTENT] [FLAGS]
Arguments
<PATH>
File path to write to (e.g., notes/idea.md).
[CONTENT]
Content to write. If omitted, reads from stdin.
Flags
--append, -a
Append to file instead of overwriting.
Examples
Write Inline Content
# Write to a file
ironclaw memory write notes/idea.md "My brilliant idea"
# Write to nested path (creates directories)
ironclaw memory write projects/website/roadmap.md "# Roadmap\n\n- Feature 1"
Write from Stdin
# Pipe content
echo "Meeting notes" | ironclaw memory write daily/$(date +%Y-%m-%d).md
# Redirect file
ironclaw memory write notes/import.md < input.txt
# Multiline input
ironclaw memory write notes/todo.md <<EOF
# TODO
- [ ] Task 1
- [ ] Task 2
EOF
Append to File
# Append to existing file
ironclaw memory write MEMORY.md "\n- New fact" --append
# Append daily notes
echo "14:00 - Team meeting" | ironclaw memory write daily/$(date +%Y-%m-%d).md --append
Output
or
ironclaw memory tree
Display the workspace directory structure.
Syntax
ironclaw memory tree [PATH] [FLAGS]
Arguments
[PATH]
Root path to start from.
- Default: “ (workspace root)
Flags
--depth, -d <NUMBER>
Maximum depth to traverse.
Examples
# Show workspace tree
ironclaw memory tree
# Show specific directory
ironclaw memory tree projects
# Show with custom depth
ironclaw memory tree --depth 5
# Show only top level
ironclaw memory tree --depth 1
Output
./
├── MEMORY.md
├── IDENTITY.md
├── HEARTBEAT.md
├── SOUL.md
├── USER.md
├── daily/
│ ├── 2024-01-15.md
│ ├── 2024-01-16.md
│ └── 2024-01-17.md
├── projects/
│ ├── website/
│ │ ├── roadmap.md
│ │ └── notes.md
│ └── api/
│ └── design.md
└── notes/
├── ideas.md
└── research.md
ironclaw memory status
Show workspace status and statistics.
Syntax
Examples
Output
Workspace Status
User: default
Files: 42
Directories: 8
Identity files:
[+] MEMORY.md
[+] HEARTBEAT.md
[+] IDENTITY.md
[+] SOUL.md
[-] AGENTS.md
[+] USER.md
[+] - File exists[-] - File does not exist
Key Identity Files
The workspace includes several important identity files:
- MEMORY.md - Core facts and context about the user
- HEARTBEAT.md - Regular updates about agent state and activities
- IDENTITY.md - Agent personality and behavior guidelines
- SOUL.md - Deeper values and philosophical grounding
- AGENTS.md - Agent-to-agent communication protocols
- USER.md - User preferences and interaction style
Workspace Structure
The workspace is organized hierarchically:
~/.ironclaw/workspace/default/
├── MEMORY.md # Core user context
├── IDENTITY.md # Agent identity
├── HEARTBEAT.md # Activity log
├── SOUL.md # Values and principles
├── USER.md # User profile
├── AGENTS.md # Multi-agent protocols
├── daily/ # Daily notes
│ └── YYYY-MM-DD.md
├── projects/ # Project-specific notes
├── notes/ # General notes
└── ... # Custom organization
Search Capabilities
The search command uses hybrid search combining:
- Full-text search - Keyword matching in content
- Semantic search - Meaning-based similarity (requires embeddings)
Results are ranked by relevance score (0.0 - 1.0) and limited by the --limit flag.
Content Indexing
Files are automatically indexed when:
- Written through
ironclaw memory write
- Created by the agent during conversations
- Modified through the workspace API
Indexing includes:
- Full-text indexing for keyword search
- Vector embeddings for semantic search (if configured)
Working with Stdin/Stdout
Pipe to Write
cat myfile.md | ironclaw memory write notes/imported.md
Read to Pipe
ironclaw memory read MEMORY.md | grep "important"
Chain Commands
ironclaw memory search "API" | head -20 | tee api-results.txt
Database Backends
Memory commands work with both PostgreSQL and libSQL backends. The backend is determined by environment variables:
# PostgreSQL
DATABASE_BACKEND=postgres
DATABASE_URL=postgresql://...
# libSQL
DATABASE_BACKEND=libsql
LIBSQL_PATH=~/.ironclaw/ironclaw.db
Troubleshooting
”Database connection required”
Memory commands require a database:
Check that DATABASE_URL or LIBSQL_PATH is set.
”No results found”
The query may be too specific, or the workspace may be empty:
# Check workspace contents
ironclaw memory tree
ironclaw memory status
# Try a broader search
ironclaw memory search "*"
“File not found”
Verify the file exists:
ironclaw memory tree
ironclaw memory status
- config - Configure workspace settings
- doctor - Check database connectivity