# OpenClaw Agent — Data Format Reference

Field-level notes for parsing `~/.openclaw/` artifacts during wiki ingest.

## Cache Root

`~/.openclaw/` — all paths below are relative to this root.

## workspace/MEMORY.md

Plain markdown. No required frontmatter — structure varies by user and agent configuration. Typically looks like:

```markdown
# Memory

## User Preferences
- Prefers concise responses without trailing summaries
- Uses pnpm over npm

## Projects
### my-api
- FastAPI app, deployed on Fly.io
- Uses Postgres via Supabase

## Patterns
- Debugging: always check logs before code changes
```

This is the single most valuable source in the entire `~/.openclaw/` tree. Read it fully before touching session logs.

## workspace/memory/YYYY-MM-DD.md

Daily note files. Auto-generated by OpenClaw at the start of each day. Format:

```markdown
# 2026-04-15

## Session: my-api refactor
- Rewrote auth middleware to use JWT instead of sessions
- Decision: keep refresh tokens in httpOnly cookies

## Session: obsidian-wiki
- Added cross-linker skill
- Fixed broken wikilinks in concepts/
```

Today's and yesterday's files are loaded into every session automatically. Files older than ~7 days have sharply diminishing signal.

## workspace/DREAMS.md

Optional. Some OpenClaw configurations generate end-of-day summaries here. Plain markdown. Treat as a lower-priority supplement to MEMORY.md — skim for novel insights not already captured in MEMORY.md.

## agents/\<agentId\>/sessions/sessions.json

Session index. JSON array:

```json
[
  {
    "id": "abc123",
    "name": "my-api refactor",
    "created_at": "2026-04-15T10:00:00Z",
    "updated_at": "2026-04-15T12:30:00Z",
    "message_count": 47,
    "agent_id": "default"
  }
]
```

Use this to:
- Build a session inventory before opening JSONL files
- Prioritize by `updated_at` (most recent = highest signal)
- Map session IDs to human-readable names

## agents/\<agentId\>/sessions/\<sessionId\>.jsonl

Per-session transcript. JSONL, append-only. One JSON object per line:

**User turn:**
```json
{"role": "user", "content": "How do I debounce a React input?", "timestamp": "2026-04-15T10:01:00Z"}
```

**Assistant turn:**
```json
{"role": "assistant", "content": "Use useCallback + useEffect with a clearTimeout...", "timestamp": "2026-04-15T10:01:02Z"}
```

**Tool call:**
```json
{"role": "tool", "name": "read_file", "input": {"path": "/home/ubuntu/app/src/App.tsx"}, "timestamp": "2026-04-15T10:01:05Z"}
```

**Tool result:**
```json
{"role": "tool_result", "name": "read_file", "content": "...", "timestamp": "2026-04-15T10:01:05Z"}
```

`role` is the primary dispatch field. `timestamp` is ISO 8601. `content` may be a string or a structured object (for multi-part responses).

## agents/\<agentId\>/sessions/\<sessionId\>-topic-\<threadId\>.jsonl

Telegram topic variant — same schema as the base session JSONL. The `-topic-<threadId>` suffix identifies which Telegram thread generated the session. Parse identically to a regular session file.

## openclaw.json

Global config. Rarely useful for ingest. Fields of interest if needed:

```json
{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "bootstrapMaxChars": 20000
    }
  },
  "skills": {
    "load": {
      "extraDirs": []
    }
  }
}
```

`agents.defaults.workspace` is the canonical path for MEMORY.md and daily notes if non-default.

## Bootstrap file priority (for reference)

OpenClaw loads context files in this order at session start:

| Priority | File | Notes |
|---|---|---|
| 10 | `AGENTS.md` | Always-on project instructions |
| 20 | `SOUL.md` | Agent identity |
| 30 | `IDENTITY.md` | Agent persona |
| 40 | `USER.md` | User profile |
| 50 | `TOOLS.md` | Tool config |
| 60 | `BOOTSTRAP.md` | Custom bootstrap |
| 70 | `MEMORY.md` | Long-term memory (workspace copy) |

All files are truncated at `bootstrapMaxChars` (default 20,000 chars) per file.

## Extraction Priority

| Source | Signal | Noise |
|---|---|---|
| `workspace/MEMORY.md` | Very high — curated, durable | Very low |
| `workspace/memory/YYYY-MM-DD.md` (recent) | High — active context | Low |
| `workspace/DREAMS.md` | Medium — summaries | Low |
| `workspace/memory/YYYY-MM-DD.md` (old) | Low — stale | Medium |
| `sessions/*.jsonl` — assistant turns | Medium | Medium |
| `sessions/*.jsonl` — tool pairs | Low | High |
| `openclaw.json` | Very low | — |
| `credentials/` | None — skip | — |