Moraine¶
Moraine is a local trace stack for agent work. It watches agent session files, normalizes them into a ClickHouse database, serves a monitor UI, and exposes an MCP server so agents can search prior sessions.
Use Moraine when you want a private record of what your agents did across
harnesses such as Codex, Claude Code, Qwen Code, Cursor, Kiro CLI, Kimi CLI,
NAC, OpenCode, Hermes, Pi Coding Agent, and Prime Agent. The default setup runs
on your machine and writes runtime state under ~/.moraine.
What You Get¶
- Unified trace database. Conversation turns, tool calls, token counts, and timestamps land in ClickHouse under a consistent schema.
- Realtime local ingest. Moraine watches Codex, Claude Code, Qwen Code, Cursor, Kiro CLI, Kimi CLI, NAC, OpenCode, Hermes, Pi Coding Agent, and Prime Agent session stores and backfills existing history on startup.
- Monitor UI. Browse sessions, inspect indexing health, and check what has
been captured at
http://127.0.0.1:8080. - MCP retrieval. Agents can search prior decisions, fixes, errors, and session context through the shared local MCP endpoint.
- Direct database access. Query
moraine.eventsand related views with your own SQL, dashboards, or experiments. - Fully local by default. Runtime state lives under
~/.moraine; nothing leaves your machine unless you point Moraine at remote infrastructure.
Moraine is under active development. Config keys, schemas, and MCP tool names can change across minor releases.
Supported Agent Harnesses¶
Moraine ships session trace ingestion adapters for these agent harnesses:
| Harness | Config value | Session traces ingested |
|---|---|---|
| Codex | codex |
JSONL session files under ~/.codex/sessions |
| Claude Code | claude-code |
JSONL project session files under ~/.claude/projects |
| Kiro CLI | kiro-cli |
Paired JSONL transcripts and JSON metadata under $KIRO_HOME/sessions/cli when set, or ~/.kiro/sessions/cli |
| Kimi CLI | kimi-cli |
wire.jsonl session traces under ~/.kimi/sessions |
| Qwen Code | qwen-code |
JSONL chat records under ~/.qwen/projects/*/chats |
| NAC | nac |
Parent sessions and managed-worker episodes from setup-resolved store.db (nac_sqlite format) |
| OpenCode | opencode |
SQLite session history from ~/.local/share/opencode/opencode*.db (default on; opencode_sqlite format) |
| Cursor | cursor |
Agent transcript JSONL under ~/.cursor/projects (default on); Cursor IDE chat history from state.vscdb SQLite databases (default on; cursor_sqlite format) |
| Hermes | hermes |
Live session JSON and trajectory JSONL traces |
| Pi Coding Agent / OMP | pi-coding-agent |
JSONL session trees under ~/.pi/agent/sessions and ~/.omp/agent/sessions |
| Prime Agent | prime-agent |
Root JSONL sessions under ~/.prime/agent/sessions and RLM child transcripts under ~/.prime/agent/session-artifacts |
Where To Start¶
Read Quickstart and Installation to install Moraine and start a local stack.
Read Configuration when you need to change watched sources, ports, ClickHouse settings, MCP defaults, or runtime paths.
Read Remote ClickHouse Tutorial when you want Moraine's default database to live in your own Docker container or personal ClickHouse server.
Read Agent MCP Search to connect agent harnesses, write effective search instructions, and understand the MCP retrieval tools.