Moraine is a local trace stack for agent work. It indexes sessions from agent harnesses such as Codex, Claude Code, Kimi CLI, 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 |
JSONL session files under ~/.codex/sessions |
| Claude Code | claude-code |
JSONL project session files under ~/.claude/projects |
| Kimi CLI | kimi-cli |
wire.jsonl session traces under ~/.kimi/sessions |
| Hermes | hermes |
Live session JSON and trajectory JSONL traces |
| Pi Coding Agent | pi-coding-agent |
JSONL session trees under ~/.pi/agent/sessions |
Install from PyPI with uv:
uv tool install moraine-cliOr install the latest release bundle:
curl -fsSL https://raw.githubusercontent.com/eric-tramel/moraine/main/scripts/install.sh | shStart the local stack:
moraine up
moraine statusThe monitor UI runs at http://127.0.0.1:8080 by default.
Moraine is most useful when your agent harness knows that it can search prior
sessions. 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?"
cargo build --workspace --locked
cargo test --workspace --locked
cargo fmt --all -- --checkThe repository-managed pre-commit hook can be installed with:
make hooks-install