# Memory System

How Claude Code and OpenClaw handle cross-session persistence.

## Claude Code: File-based memory

Claude Code reads files at session start and writes them back on request.

**Mechanism:**
- `CLAUDE.md` files at `~/.claude/CLAUDE.md` (global), repo root, and subdirectories
- Auto-memory: files listed in `CLAUDE.md` under `memory:` are auto-loaded
- Project files: any file you explicitly tell Claude to read at session start
- No background process, no indexing, no database

**Properties:**
- Deterministic: Claude reads exactly what you wrote
- No semantic search: retrieval is positional, not by meaning
- Fully transparent: open any file to see what Claude knows
- Hierarchical: global < project < subdirectory, each level can override

## OpenClaw: Hybrid memory

OpenClaw maintains memory through a combination of structured logs and vector search.

**Mechanism:**
- Daily markdown logs with structured entries
- `MEMORY.md` as a curated summary file
- SQLite-vec or LanceDB for vector storage
- BM25 + cosine similarity for retrieval (hybrid search)

**Properties:**
- Semantic search: "find notes about authentication" works even without exact keywords
- Automatic logging: entries written by the agent during execution
- Higher complexity: requires a running database
- Retrieval can surface relevant context not explicitly linked

## Comparison

| Property             | Claude Code         | OpenClaw                  |
|----------------------|---------------------|---------------------------|
| Storage              | Plain files         | Files + SQLite/LanceDB    |
| Retrieval            | Positional/explicit | BM25 + cosine (hybrid)    |
| Semantic search      | No                  | Yes                       |
| Setup complexity     | Zero                | Moderate                  |
| Transparency         | Full                | Partial                   |
| Cross-session        | Yes (manual)        | Yes (automatic)           |

## Recommendation

For most projects, Claude Code's file-based approach is sufficient. Keep MEMORY.md
short and curated. Long files degrade quality faster than missing context does.

Use this directory (`memory/`) to store any project state that should outlast a session.