Moraine: Unified Agent Tracing

Moraine, a local trace stack for agent work, indexes sessions from agent harnesses such as Codex, Claude Code, Kimi CLI, OpenCode, Hermes, and Pi Coding Agent into ClickHouse, providing a unified local record of agent activity across providers. The tool offers a monitor UI and MCP retrieval for searchable long-term memory, with active development and potential schema changes.

Moraine is a local trace stack for agent work. It indexes sessions from agent harnesses such as Codex, Claude Code, Kimi CLI, OpenCode, Hermes, and Pi Coding Agent into ClickHouse, serves a monitor UI, and exposes MCP retrieval over the indexed history. Agents get searchable long-term memory through MCP. You get a unified local record of what happened across providers, including tools, tokens, and conversation history. Moraine is under active development. Config keys, schemas, and MCP tools can change across minor releases. Moraine ships session trace ingestion adapters for these agent harnesses: | Harness | Config value | Session traces ingested | |---|---|---| | codex ~/.codex/sessions Claude Code https://code.claude.com/docs/en/overview claude-code ~/.claude/projects Kimi CLI https://moonshotai.github.io/kimi-cli/en/ kimi-cli wire.jsonl session traces under ~/.kimi/sessions OpenCode https://opencode.ai/ opencode ~/.local/share/opencode/opencode .db default on; opencode sqlite format Cursor https://cursor.com/docs cursor ~/.cursor/projects default on ; Cursor IDE chat history from state.vscdb SQLite databases default on; cursor sqlite format Hermes https://hermes-agent.nousresearch.com/docs/ hermes Pi Coding Agent https://pi.dev/docs/latest pi-coding-agent ~/.pi/agent/sessions uv tool install moraine-cli moraine setup moraine up moraine setup creates or repairs ~/.moraine/config.toml and guides plugin or MCP registration for detected agent harnesses. The monitor UI runs at http://127.0.0.1:8080 by default. For release bundles, upgrades, project-scoped setup, and other harnesses, see the Quickstart and Installation https://eric-tramel.github.io/moraine/quickstart.html . Use moraine setup to install or update the Moraine plugins for Claude Code, Codex, and Hermes, or to register Moraine MCP for supported harnesses such as OpenCode, Cursor, Kimi CLI, and Pi Coding Agent. The integrations use the moraine CLI on your PATH and the running local stack. Start a new agent session after installing an integration. Claude Code, Codex, and Hermes sessions get moraine:session-search , moraine:realtime-peek , and moraine:bug-report guidance, and Moraine MCP tools are exposed with each harness's MCP naming scheme. Then ask: What are my agents doing right now? The user-scoped plugins can search the host-wide Moraine history visible to your user. For project-scoped setup, duplicate MCP cleanup, and other clients, see Agent MCP Search https://eric-tramel.github.io/moraine/agent-mcp-search/index.html . The Claude Code, Codex, and Hermes plugins already bundle Moraine search guidance. If you use manual MCP registration or another harness, add the following guidance to your global harness instructions, such as ~/.codex/AGENTS.md for Codex or ~/.claude/CLAUDE.md for Claude Code: - You have access to all past agent sessions whether codex, claude, hermes, etc., anything via moraine search tools. - Any time the user asks about information not located within your context, that you can't see or don't know, but implies that you should know, it is because it was a past conversation. You can reference and search for this conversation with moraine search tools or session listing. - Moraine search tooling is built around BM25 keyword search, so target your queries to keywords rather than questions. There is no semantic search. - Successful keyword searches often go from broad to narrow. Sometimes this narrowing isn't successful, in which case, you can always back up and try a different path. - Moraine has a real-time view of agent sessions. You can use it to peek on active AI agent sessions, including your own, sessions running in different harnesses, sessions that are sub-agents of your current conversation, or even their subagents. All agent work, in realtime, is visible to you. With this you can do operations like the following: claude -p "What are my agents doing right now?" codex exec "What are my agents doing right now?" hermes -z "What are my agents doing right now?" cargo build --workspace --locked cargo test --workspace --locked cargo fmt --all -- --check The repository-managed pre-commit hook can be installed with: make hooks-install To put the current checkout tip-of-branch, no tagged release needed onto your host for testing, build and install it over the active moraine on your PATH: make install This release-builds the host target and installs through the same scripts/install.sh path end users get. ClickHouse is skipped by default make install INSTALL ARGS="--with-clickhouse" to include it . See scripts/dev/install-host.sh --help for the full set of options.