Skip to content

Quickstart

Get Lerim running in under 5 minutes — from installation to your first knowledge query.

Prerequisites

Before you begin, make sure you have:

  • Python 3.10 or higher
  • Docker installed (recommended)
  • An LLM API key — you only need a key for the provider(s) you configure

Tip

If you don't have Docker, you can run Lerim directly using lerim serve instead of lerim up. See the installation guide for details.

Get started in 5 steps

Install Lerim

Install Lerim via pip:

pip install lerim

Verify the installation:

lerim --version

You should see output like:

lerim, version 0.1.69

Set up API keys

Lerim needs an LLM provider for extraction and querying. Set at least one API key:

export OPENCODE_API_KEY="..."

The shipped default.toml often uses provider = "opencode_go" for roles. Set this key unless you override providers in ~/.lerim/config.toml.

export MINIMAX_API_KEY="sk-cp-..."
export ZAI_API_KEY="..."

Use when [roles.*] uses MiniMax and Z.AI.

export OPENROUTER_API_KEY="sk-or-v1-..."

export OPENAI_API_KEY="sk-..."

Note

You only need API keys for the providers you configure. Match keys to [roles.*] in ~/.lerim/config.toml (see shipped src/lerim/config/default.toml for package defaults). See model roles.

Initialize and add a project

Run the interactive setup wizard:

lerim init

This will:

  • Detect your installed coding agents
  • Ask which agents you want to connect
  • Write the config to ~/.lerim/config.toml
  • Check for Docker availability

Example session:

Welcome to Lerim.

Which coding agents do you use?
  claude (detected) [Y/n]: y
  cursor (detected) [Y/n]: y
  codex (not found) [y/N]: n
  opencode (not found) [y/N]: n

Config written to ~/.lerim/config.toml
Agents: claude, cursor

Docker: found

Now add your first project:

lerim project add .

This registers the current directory and creates a .lerim/ folder for project-specific memories.

Tip

You can add multiple projects. Each project gets its own .lerim/ directory for scoped memories.

Start the Lerim service

Start Lerim as a Docker service:

lerim up

Output:

Starting Lerim with 1 projects and 2 agents...
Lerim is running at http://localhost:8765

This starts a Docker container that:

  • Runs the sync + maintain daemon loop
  • Exposes the JSON API at http://localhost:8765 for CLI commands

Note

The first time you run lerim up, it will pull the Docker image from the registry. This may take a minute.

Use Lerim Cloud for the web UI (sessions, memories, settings). http://localhost:8765/ may show a short stub page linking to Cloud.

Query your memories

Now you can query your agent memories. Try these commands:

lerim ask "Why did we choose this architecture?"

lerim memory search "database migration"

lerim memory list

lerim status

Example output from lerim status:

Lerim status:
- connected_agents: 2
- memory_count: 0
- sessions_indexed_count: 0
- queue: {'pending': 0, 'processing': 0, 'failed': 0}

Tip

If you don't have any memories yet, use your coding agents as usual. Lerim will automatically sync sessions in the background and extract decisions and learnings.

Teach your agent about Lerim

Install the Lerim skill so your coding agent knows how to query past context:

lerim skill install

This copies SKILL.md and cli-reference.md into ~/.agents/skills/lerim/ and ~/.claude/skills/lerim/ (see lerim skill install --help).

At the start of a coding session, tell your agent:

Check lerim for any relevant memories about [topic you're working on].

Your agent will run lerim ask or lerim memory search to pull in past decisions and learnings before it starts working.

Force a sync

By default, Lerim syncs sessions automatically in the background. To trigger a manual sync:

lerim sync

You can limit the number of sessions to sync:

lerim sync --max-sessions 5

Or sync only a specific agent:

lerim sync --agent claude

Managing the service

lerim down

lerim down && lerim up

lerim logs

lerim logs --follow

lerim project list

What's happening in the background?

  1. Session indexing — Lerim watches your agent session stores for new traces
  2. Extraction — When new sessions are detected, Lerim extracts decision and learning candidates using DSPy pipelines
  3. Deduplication — Candidates are compared against existing knowledge to avoid duplicates
  4. Storage — New entries are written as markdown files to .lerim/memory/ (project scope)
  5. Refinement — The maintain loop periodically merges duplicates, archives low-value entries, and applies time decay to keep the context graph clean

Next steps

  • CLI reference

    Master all Lerim commands

    CLI Reference

  • Configuration

    Customize model providers, tracing, and more

    Configuration

  • Memory model

    Understand how memories are stored and structured

    Memory model

  • Lerim Cloud

    Web UI (sessions, memories, pipeline)

    Web UI