MultiPhysicsVault/.agents/skills/openclaw-history-ingest/references/openclaw-data-format.md

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:

# 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:

# 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:

[
  {
    "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:

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

Assistant turn:

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

Tool call:

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

Tool result:

{"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:

{
  "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	—