Lerim compiles completed agent traces into cited, reusable context.

Lerim sits above agent traces, compiles useful signal into cited context and eval assets, and gives future agents the operating memory they need before work begins.

Docs · Benchmarks · Examples · PyPI · License

Lerim

Lerim is a context compiler for repeated AI agent workflows.

Agents leave traces everywhere: terminals, tools, tickets, code reviews,
support cases, research runs. Most of that history is too noisy to reuse
directly. Lerim filters those traces into evidence-backed context records and
eval-ready signal: the decisions, constraints, facts, preferences, corrections,
and handoffs future agents should not have to rediscover, each linked back to
the source session.

What The Demo Shows

Most routine traces produce no durable record. Lerim's value is compact, cited
context, not more logs.

Quick Install

Requires Python 3.11+ and Node.js 20+. Lerim parses agent transcripts
with Letta's trajectory normalizer, an
npm package, so node is a hard runtime requirement — there is no fallback
parser. lerim init verifies node and installs the pinned normalizer for you.

pip install lerim
lerim init
lerim connect auto --mode auto
lerim project add .
lerim up

If node is missing, install it first (macOS: brew install node, Linux:
https://nodejs.org/en/download) and re-run lerim init. The Docker image ships
node and the pinned normalizer already.

Native trace sources ingest completed local sessions where a stable trace store
exists; MCP setup writes tool entries for compatible agents. See
Agent Support for what is verified per agent.

Then ask Lerim what a future agent should know:

lerim answer "What context should I know before working in this project?"

Why Lerim

AI agents now triage tickets, investigate incidents, research markets, prepare
handoffs, review policies, analyze customers, and change software. Every run
leaves a trace, and most traces are too long, too noisy, and too
platform-specific for the next agent to reuse.

Without a durable context layer, decisions get re-debated, constraints get
rediscovered, preferences get ignored, corrections never become reusable
context or eval signal, and every new session starts too close to zero.

Lerim fits best where one repeated workflow has trace access, a workflow owner,
privacy constraints, and a measurable quality failure to fix. Coding is the
proof-rich workflow today because native trace parsing is mature there; support,
incident, research, and compliance run the same compiler through custom traces.

Key Capabilities

• Trace-to-context extraction. ingest reads supported sources and custom clean-trace folders, extracts reusable signal, and can archive routine runs without creating noisy durable records.
• Shared context across agents. What one agent learns can become useful context for a different agent or workflow later.
• Context curation. Lerim consolidates overlap, archives weak records, and keeps the context layer compact.
• Derived context graph. Lerim links related decisions, constraints, evidence, facts, and handoffs for curation and future/hosted visualization.
• Query and startup context. Agents can ask questions against accumulated context or start from a compact context brief.
• Evidence-backed memory. Useful decisions, constraints, preferences, facts, and handoffs stay linked to the work that produced them.
• Skill updates. Register a skill or instruction file, let Lerim propose evidence-backed edits from learned context, then review the diff in the dashboard before applying it.
• Custom source profiles. Coding, support, and incident workflows share one compiler, and teams can register YAML profiles for their own verticals with focus, noise, evidence, and scope rules.

What Lerim Is Not

• Not a raw transcript replay tool.
• Not a broad memory_save bucket for agents to write arbitrary memories.
• Not a replacement for observability. Observability keeps the trace; Lerim compiles reusable context from completed source sessions.
• Not a claim that every listed agent has native completed-session ingestion. MCP recall is useful, but it is different from native trace ingestion.

Agent Support

Lerim has two integration layers:

• Native trace parsing reads completed local sessions through the
  trajectory normalizer and feeds Lerim's compiler.
• MCP support lets compatible agents query Lerim context and explicitly submit completed sessions through lerim_trace_submit; it is not automatic local-history capture.

See the integration matrix for the exact support
boundary and evidence level per agent.

MCP Quickstart

Install Lerim into an MCP client (dry-run first, then write):

lerim connect gemini-cli --mode mcp --dry-run
lerim connect gemini-cli --mode mcp

MCP tools: lerim_context_brief, lerim_context_answer, lerim_context_search,
lerim_records_list, lerim_context_feedback, lerim_trace_submit,
lerim_ingest_status.

See MCP Quickstart for the generic client
config, the absolute-path rationale, and verification.

Benchmarks

Benchmark numbers live in docs, not in a marketing scoreboard. Start with
Benchmark Overview for the map and reporting rules:

• Benchmark Suite: what each benchmark
  surface measures and its boundary.
• Lerim Results: first-party raw artifacts,
  commands, and boundaries, including retrieval-only and aggregate-only scope.
• Market Comparison: source-backed rows
  with provenance for each external number.

Skill Updates

Lerim can also update the instructions future agents use. Register a skill
directory, SKILL.md, AGENTS.md, CLAUDE.md, or another instruction file;
Lerim scans scoped context records from past traces and proposes small,
evidence-backed edits. Review each unified diff in the dashboard before applying.
Targets default to review mode; auto-apply is opt-in and bounded by policy.

lerim skill target add ~/.agents/skills/clean-code \
  --description "Keep simplification guidance current"
lerim skill refresh clean-code
lerim dashboard

See Skill Updates for the dashboard workflow and
CLI: lerim skill for command details.

Custom & Non-Coding Agents

Lerim is not only for coding agents. Support, incident and security operations,
research, compliance, revenue, and other custom business agents feed the same
compiler through clean JSONL traces and a signal profile that matches the
workflow.

Bundled signal profiles cover the common verticals out of the box:

List them with lerim profile list / lerim profile show research, or write
your own in a few minutes. Start at
Custom & Non-Coding Agents for the full path,
or jump to a worked demo:
support ·
incident ·
research ·
compliance.

Custom Agent Traces

Built-in connect sources cover Claude Code, Codex CLI, Letta Code, and
OpenClaw. For any other agent or business workflow, register already-clean
trajectory-v1 JSONL — one .jsonl file per completed session. Custom mode has no
normalizer step, so you own export, cleaning, redaction, and retention before
files enter the folder.

See Custom Trace Folders for the
trajectory-v1 schema and a paste-in prompt that generates a cleaner for your
source, and Submit a Custom Agent Trace
for the lerim trace import profile/scope flags.

Common Commands

lerim status              # pipeline and queue state
lerim ingest               # compile completed sessions into context
lerim curate               # consolidate and prune records
lerim answer "What decisions exist about caching?"
lerim connect auto         # (re)write agent integrations
lerim context-brief show   # compact startup context

Full command reference: CLI Overview.

Development

uv venv && source .venv/bin/activate
uv pip install -e '.[test]'
tests/run_tests.sh unit

Node.js 20+ must be on PATH; the trace-parsing tests shell out to the pinned
@letta-ai/trajectory normalizer.

See the Contributing Guide
for full dev setup, the live test suites, and the release checklist.

To read the codebase, start with
src/lerim/README.md and
docs/concepts/how-it-works.md.

License

Lerim core is Apache-2.0. The local CLI, runtime, self-hosted sync server,
native trace parsing, context DB schema, benchmark scripts, and integration docs
stay usable without any paid account. Any hosted or commercial offering sits
outside the open-source core. See COMMERCIAL.md for the open-source scope.

Contributing

Contributions are welcome.

Good starting points include:

• new harness adapters, contributed upstream to trajectory so every consumer gets them
• custom trace-folder examples
• extraction quality
• context curation quality
• context graph link quality
• docs and demo examples

Helpful links:

• Contributing Guide
• Open issues
• Trace-source plumbing: src/lerim/adapters/
• Upstream adapter guide: letta-ai/trajectory