Agent Memory

GoClaw implements a layered memory system that combines file-based memory, semantic search, and a structured knowledge graph.

Memory Architecture

┌──────────────────────────────────────────────────────────────────┐
│                      Agent Memory System                          │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │ Workspace Memory│  │ Semantic Search │  │  Memory Graph   │  │
│  │ (File-Based)    │  │ (Embeddings)    │  │  (Knowledge)    │  │
│  │                 │  │                 │  │                 │  │
│  │ MEMORY.md       │  │ memory_search   │  │ memory_graph_   │  │
│  │ memory/*.md     │  │ transcript      │  │ recall/query    │  │
│  │ USER.md, SOUL.md│  │                 │  │ store/update/...│  │
│  │                 │  │                 │  │                 │  │
│  │ Human-readable  │  │ SQLite+Ollama   │  │ Entities &      │  │
│  │ Markdown files  │  │ Vector search   │  │ Relationships   │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
│                                                                   │
│        Compatibility          Hybrid Search         Future        │
└──────────────────────────────────────────────────────────────────┘

Memory Systems Overview

Roadmap: Memory Graph is the future direction for GoClaw’s memory system. It provides automatic extraction, structured storage, and smarter recall compared to file-based memory. Once stable, it will become the primary memory system, with workspace memory remaining for human-readable logs and OpenClaw compatibility.

Workspace Memory

Traditional file-based memory that the agent can read and write directly.

Memory Files

How It Works

1. Agent reads memory files at session start (via prompt cache)
2. Agent writes to memory files using write or edit tools
3. Memory persists across sessions
4. Agent decides what’s worth remembering

Best Practices

From AGENTS.md:

• Write important context to memory/YYYY-MM-DD.md as it happens
• Periodically review daily notes and update MEMORY.md with lasting insights
• Include source attribution: (told me directly), (from website.com), (inferred)

Semantic Memory

Embeddings-based search over memory files and conversation transcripts.

Components

How It Works

1. Memory files and transcripts are chunked and embedded
2. Embeddings stored in SQLite alongside the content
3. Search queries are embedded and compared using cosine similarity
4. Hybrid scoring combines vector similarity + keyword matching

Search Tools

memory_search — Search memory files:

{
  "query": "what did we decide about the API design?",
  "maxResults": 5
}

transcript — Search conversation history:

{
  "action": "search",
  "query": "when did we discuss deployment",
  "maxResults": 5
}

Memory vs Transcripts

Configuration

Memory Search

{
  "memory": {
    "enabled": true,
    "query": {
      "maxResults": 6,
      "minScore": 0.35,
      "vectorWeight": 0.7,
      "keywordWeight": 0.3
    },
    "paths": []
  }
}

Transcript Search

Transcript search uses the same embedding infrastructure configured for memory search.

See Embeddings for embedding model configuration.

Compaction Recovery

When context is compacted during long sessions, recent conversation history is lost. The agent can recover using:

1. transcript — Find relevant past conversation chunks
2. memory_search — Check if context was saved to memory files
3. Daily notes — Read memory/YYYY-MM-DD.md for recent context

Prevention

Configure memory flush prompts to remind the agent to save context before compaction:

{
  "session": {
    "memoryFlush": {
      "enabled": true,
      "thresholds": [
        {"percent": 50, "prompt": "Consider noting key decisions."},
        {"percent": 75, "prompt": "Write important context now."}
      ]
    }
  }
}

Memory Graph

The Memory Graph is a semantic knowledge graph that provides structured, queryable memory with automatic extraction from conversations.

Key Features

• Automatic extraction — Entities, preferences, and facts extracted from conversations
• Structured storage — Typed entities with relationships (not free-form text)
• Smart recall — Relevant context automatically injected into system prompt
• CRUD operations — Agent can store, update, query, and forget memories

Tools

Real-Time Memory Formation

When agent-driven extraction guidance is enabled, the agent is expected to complete the memory workflow before sending its user-facing response for anything it judged memory-worthy:

1. use memory_graph_recall first
2. decide whether to skip, enrich/update, or store new knowledge
3. use memory_graph_store only when something genuinely new or updated should be preserved
4. then continue with the normal response

Recognition alone is not enough. If the agent decides something is worth remembering, it should not simply note that internally and continue without invoking the memory tool workflow.

When to Use

Memory Graph is better than file-based memory for:

• Facts that need to persist (“user prefers dark mode”)
• Information that should auto-surface in context
• Structured data (preferences, relationships, events)

File-based memory is better for:

• Detailed notes and logs
• Human-readable records
• OpenClaw compatibility

See Memory Graph for full documentation.

OpenClaw Compatibility

GoClaw’s file-based memory system is compatible with OpenClaw:

• Same file locations (MEMORY.md, memory/, etc.)
• Same semantic search tools
• Shared embedding database

This enables running GoClaw alongside OpenClaw with a unified workspace. Memory Graph is a GoClaw-specific feature not available in OpenClaw.

See Also

• Memory Graph — Structured knowledge graph (beta)
• Memory Search — memory_search tool
• Transcript Search — transcript tool
• Embeddings — Embedding infrastructure
• Session Management — Compaction and memory flush