ironclaw memory

Query and manage IronClaw workspace memory

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 workspace
• write - Write content to a workspace file
• tree - Show workspace directory tree
• status - 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.

• Default: 5
• Maximum: 50

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...

Score indicators:

• =====> - 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

Wrote to notes/idea.md

or

Appended to MEMORY.md

---

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.

• Default: 3

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

ironclaw memory status

Examples

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

Markers:

• [+] - 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:

1. Full-text search - Keyword matching in content
2. 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:

ironclaw doctor

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

Related Commands

• config - Configure workspace settings
• doctor - Check database connectivity