Moraine

Moraine

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.

Screenshots

Documentation

• Home
• Introduction
• Quickstart and Installation
• Configuration
• Remote ClickHouse
• Agent MCP Search

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
Kimi CLI	kimi-cli	wire.jsonl session traces under ~/.kimi/sessions
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	pi-coding-agent	JSONL session trees under ~/.pi/agent/sessions

Quickstart

Install from PyPI with uv:

uv tool install moraine-cli

Or install the latest release bundle:

curl -fsSL https://raw.githubusercontent.com/eric-tramel/moraine/main/scripts/install.sh | sh

Start the local stack:

moraine up
moraine status

The monitor UI runs at http://127.0.0.1:8080 by default.

Connect Claude Code or Codex

After moraine up, install the Moraine plugin for your agent harness. The plugins register the MCP search server and bundle guidance for searching prior sessions, but they still use the moraine CLI on your PATH and the running local stack.

For Claude Code:

claude plugin marketplace add eric-tramel/moraine --sparse .claude-plugin plugins
claude plugin install moraine@moraine

For Codex:

codex plugin marketplace add eric-tramel/moraine \
  --sparse .agents/plugins \
  --sparse plugins/moraine \
  --sparse plugins/moraine-dev
codex plugin add moraine@moraine

Start a new agent session after installing the plugin. Claude Code sessions get the moraine:session-search and moraine:realtime-peek skills, and Moraine MCP tools are exposed as mcp__plugin_moraine_moraine__*. 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.

Agent Harness Guidance

The Claude Code and Codex 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: