moraine

Moraine indexes all of your Claude Code and Codex traces in realtime into a searchable, unfied database.

🤖 Your Agents Get: a searchable long-term memory.
🌝 You Get: a unified record of everything they've done across providers. Tools, Tokens, and Talk.

Specifically, Morine provides:

• The Dataplane to Your Agentic Era: the database is yours, take inspiration from our tooling and schema definitions and build your own apps ontop of moraine's DB.
• Agent memory via MCP: agents search and retrieve context from past conversations
• Unified trace database: every conversation turn, tool call, and token count in one place — query it however you want
• Monitor UI: browse sessions, check ingestion health, inspect what your agents have been doing
• Continually Optimized Search Tooling: improvements to realtime search performance are an ongoing effort in the project, and we're aiming to drive down real-time search latency as much as can.
• Fully local: nothing leaves your machine, unless you want it to (and set up a remote db instance).

Quickstart

Install moraine (prebuilt bundle) to ~/.local/bin.

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

Afterwards, just make sure to have ~/.local/bin on your path (e.g. in your .zshrc, .bashrc, etc.).

Start the stack and confirm it is healthy:

which moraine
moraine up
moraine status

Open the monitor UI at http://127.0.0.1:8080.

Run a Claude Code or Codex session as you normally would, you'll see row counts and the ingest heartbeat move as your sessions are indexed.

Use moraine status --output rich --verbose for a detailed breakdown.

Connect an Agent (MCP)

While Moraine can be used for many purposes, a direct one is the search tooling we've built into a custom
BM25 search MCP, which will allow your agents to self-review past conversations across agent harnesses.

To wire it into Claude Code, add this to your .mcp.json:

{
  "mcpServers": {
    "moraine": {
      "command": "moraine",
      "args": ["run", "mcp"]
    }
  }
}

Or add to Codex:

codex mcp add conversation-search -- moraine run mcp

For the full tool contract and integration guidance, see docs/mcp/agent-interface.md.

Query the Database Directly

Moraine's ClickHouse tables are yours to query. The MCP search path is optimized for fast agent retrieval, but the underlying database holds the complete trace of every session — conversation turns, tool calls, token usage, timestamps, and more.

Connect to ClickHouse and explore:

clickhouse client -d moraine

-- sessions and their row counts
SELECT session_id, count(*) as events
FROM conversation_events
GROUP BY session_id
ORDER BY events DESC
LIMIT 10;

-- token usage across sessions
SELECT session_id,
       sum(input_tokens) as input,
       sum(output_tokens) as output
FROM conversation_events
WHERE input_tokens > 0
GROUP BY session_id
ORDER BY output DESC
LIMIT 10;

See sql/ for the full schema and view definitions.

Watched Sources

By default, Moraine watches:

Configurable in ~/.moraine/config.toml under [[ingest.sources]].

Common Commands

Configuration

Default config lives in config/moraine.toml. Runtime config is resolved in order:

1. --config <path> flag
2. MORAINE_CONFIG env var (and MORAINE_MCP_CONFIG for MCP)
3. ~/.moraine/config.toml

To customize, copy config/moraine.toml to ~/.moraine/config.toml and edit.

Moraine stores all runtime state under ~/.moraine. If ClickHouse is not already installed, moraine up auto-installs a managed build.

Install From Source

Requires a Rust toolchain (cargo, rustc):

git clone https://github.com/eric-tramel/moraine.git ~/src/moraine
cd ~/src/moraine
for crate in moraine moraine-ingest moraine-monitor moraine-mcp; do
  cargo install --path "apps/$crate" --locked
done

Further Reading

• Operations runbook: docs/operations/build-and-operations.md
• Migration notes: docs/operations/migration-guide.md
• System internals: docs/core/system-architecture.md
• MCP tool contract: docs/mcp/agent-interface.md