Skip to main content
This guide will take you from zero to querying your first agent memories in under 5 minutes.

​
Prerequisites

Before you begin, make sure you have:
  • Python 3.10 or higher
  • Docker installed (recommended)
  • An LLM API key (OpenRouter, OpenAI, or Anthropic)
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

1

Install Lerim

Install Lerim via pip:
pip install lerim
Verify the installation:
lerim --version
You should see output like:
lerim, version 0.1.52
2

Set up API keys

Lerim needs an LLM provider for extraction and querying. Set at least one API key:
export OPENROUTER_API_KEY="sk-or-v1-..."
OpenRouter is the default provider. It gives you access to multiple models including GPT-5-nano (used for extraction) and Grok-4.1-fast (used for agents).
3

Initialize and add a project

Run the interactive setup wizard:
lerim init
This will:
  • Detect your installed coding agents (Claude Code, Codex, Cursor, OpenCode)
  • 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

Next steps:
  lerim project add /path/to/repo   # register a project
  lerim up                           # start the Docker service
Now add your first project:
lerim project add .
This registers the current directory and creates a .lerim/ folder for project-specific memories.
You can add multiple projects. Each project gets its own .lerim/ directory for scoped memories.
4

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
  • Serves the dashboard at http://localhost:8765
  • Exposes the HTTP API for CLI commands
The first time you run lerim up, it will pull the Docker image from the registry. This may take a minute.
Open the dashboard in your browser:
open http://localhost:8765
5

Query your memories

Now you can query your agent memories. Try these commands:
lerim ask "Why did we choose this architecture?"
Example output from lerim status:
Lerim status:
- connected_agents: 2
- memory_count: 0
- sessions_indexed_count: 0
- queue: {'pending': 0, 'processing': 0, 'failed': 0}
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: 
npx skills add lerim-dev/lerim-cli
This works with Claude Code, Codex, Cursor, Copilot, Cline, Windsurf, OpenCode, and other agents that support skills. 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
Example output: 
Sync:
- sessions_processed: 3
- new_memories: 5
- updated_memories: 1
- duration_seconds: 12.4
You can limit the number of sessions to sync: 
lerim sync --max-sessions 5
Or sync only a specific agent: 
lerim sync --agent claude

​
Run memory maintenance

Lerim automatically maintains memories in the background, but you can trigger it manually: 
lerim maintain
This will:
  • Merge duplicate memories
  • Archive low-value entries
  • Consolidate related memories
  • Apply time-based decay
Example output: 
Maintain:
- memories_merged: 2
- memories_archived: 1
- duration_seconds: 8.2

​
Managing the service

lerim down

​
Running without Docker

If you prefer not to use Docker, run Lerim directly: 
lerim connect auto           # detect agent platforms
lerim serve                  # start API server + dashboard + daemon loop
Then use lerim ask, lerim sync, lerim status, etc. as usual.

​
What’s happening in the background?

  1. Session indexing: Lerim watches your agent session stores (e.g., ~/.claude/projects/, ~/Library/Application Support/Cursor/User/globalStorage/)
  2. Extraction: When new sessions are detected, Lerim extracts decision and learning candidates using DSPy pipelines
  3. Deduplication: Candidates are compared against existing memories to avoid duplicates
  4. Storage: New memories are written as markdown files to .lerim/memory/ (project scope) or ~/.lerim/memory/ (global scope)
  5. Refinement: The maintain loop periodically merges duplicates, archives low-value entries, and applies time decay

​
Next steps

CLI reference

Master all Lerim commands

Configuration

Customize model providers, tracing, and more

Memory model

Understand how memories are stored and structured

Dashboard

Explore the web UI features
Having issues? Check the troubleshooting guide or open an issue on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us