> ## 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 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 ```bash theme={null} ironclaw memory search [FLAGS] ``` ### Arguments **``** Search query string. ### Flags **`--limit, -l `** Maximum number of results to return. * Default: `5` * Maximum: `50` ### Examples ```bash theme={null} # 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 ```bash theme={null} 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 ```bash theme={null} ironclaw memory read ``` ### Arguments **``** File path relative to workspace root (e.g., `MEMORY.md`, `daily/2024-01-15.md`). ### Examples ```bash theme={null} # 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: ```markdown theme={null} # Memory Core facts and context about the user: - Name: Alice - Role: Software Engineer - Current project: Building AI assistant - Preferred language: Python ... ``` ### Error Handling ```bash theme={null} ironclaw memory read nonexistent.md # Error: File not found: nonexistent.md ``` *** ## ironclaw memory write Write content to a workspace file. ### Syntax ```bash theme={null} ironclaw memory write [CONTENT] [FLAGS] ``` ### Arguments **``** 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 ```bash theme={null} # 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 ```bash theme={null} # 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 <`** Maximum depth to traverse. * Default: `3` ### Examples ```bash theme={null} # 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 ```bash theme={null} ./ ├── 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 ```bash theme={null} ironclaw memory status ``` ### Examples ```bash theme={null} ironclaw memory status ``` ### Output ```bash theme={null} 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 ```bash theme={null} cat myfile.md | ironclaw memory write notes/imported.md ``` ### Read to Pipe ```bash theme={null} ironclaw memory read MEMORY.md | grep "important" ``` ### Chain Commands ```bash theme={null} 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: ```bash theme={null} # 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: ```bash theme={null} 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: ```bash theme={null} # Check workspace contents ironclaw memory tree ironclaw memory status # Try a broader search ironclaw memory search "*" ``` ### "File not found" Verify the file exists: ```bash theme={null} ironclaw memory tree ironclaw memory status ``` ## Related Commands * [config](/cli/config) - Configure workspace settings * [doctor](/cli/doctor) - Check database connectivity