Native workflow

If you prefer not to use Docker, or you’re developing Lerim itself, you can run the service directly on your host machine. This gives you more control and visibility into the process.

When to use native mode

Choose native over Docker when:

Developing Lerim: You’re working on the Lerim codebase and need fast iteration
Custom environments: You have specific Python version requirements or system dependencies
No Docker: Docker isn’t available or allowed in your environment
Debugging: You want direct access to the process for debugging and profiling

For production use or hands-off operation, Docker workflow is recommended.

Setup

Install Lerim

pip install lerim

Or for development:

git clone https://github.com/lerim-dev/lerim-cli.git
cd lerim-cli
uv venv && source .venv/bin/activate
uv pip install -e .

Set API keys

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

export OPENROUTER_API_KEY="sk-or-..."   # default provider
# or
export OPENAI_API_KEY="sk-..."
# or
export ZAI_API_KEY="..."

Initialize config

Run the interactive setup:

lerim init

This creates ~/.lerim/config.toml with your agent connections.

Connect agents

Auto-detect and connect your coding agents:

lerim connect auto

Add projects

lerim project add ~/codes/my-app
lerim project add .

Running the server

The lerim serve command starts everything you need in a single process:

HTTP API on port 8765 (configurable)
Web dashboard at http://localhost:8765
Background daemon for sync and maintain loops

lerim serve

Output:

Lerim serve running at http://0.0.0.0:8765/
Sync: 3 sessions enqueued, 2 extracted
Maintain: merged 1 duplicate, archived 0 stale

lerim serve is the Docker container entrypoint, but works perfectly on the host. It runs a continuous daemon loop with automatic sync and maintenance.

Custom host and port

lerim serve --host 0.0.0.0 --port 8765
lerim serve --host 127.0.0.1 --port 9000

Running the daemon manually

If you want more control over the daemon behavior, run it separately from the HTTP server:

lerim daemon

This runs a continuous loop: sync (index + extract) then maintain (refine), repeating at configurable intervals.

One-shot execution

Run a single sync + maintain cycle and exit:

lerim daemon --once

Useful for:

Testing extraction pipelines
Cron jobs or scheduled tasks
CI/CD integration

Custom poll interval

Override sync and maintain intervals uniformly:

lerim daemon --poll-seconds 120  # poll every 2 minutes

Minimum poll interval is 30 seconds. Lower values risk overloading your LLM provider.

Service commands

Once lerim serve or lerim daemon is running, these commands talk to the HTTP API:

lerim ask "Why did we choose Postgres?"

If the server isn’t running, these commands fail:

Lerim is not running. Start with: lerim up (Docker) or lerim serve (direct)

Local-only commands

Some commands run directly on the host without needing a server:

lerim memory search "database migration"

These commands work whether or not the daemon is running.

Development workflow

For active development on Lerim:

Clone and install

git clone https://github.com/lerim-dev/lerim-cli.git
cd lerim-cli
uv venv && source .venv/bin/activate
uv pip install -e .

Setup Lerim

lerim init
lerim project add .  # track the Lerim repo itself

Run tests

tests/run_tests.sh unit
tests/run_tests.sh all

Start development server

lerim serve

Changes to the code require restarting the server.

Test extraction

lerim sync --max-sessions 5
lerim memory list

Process management

Unlike Docker, native mode requires manual process management.

Running in background

Use nohup or screen to keep Lerim running after logout:

nohup lerim serve > lerim.log 2>&1 &

Or with screen:

screen -S lerim
lerim serve
# Press Ctrl+A, then D to detach

Reattach later:

screen -r lerim

Systemd service

For Linux systems, create a systemd unit file:

/etc/systemd/system/lerim.service

[Unit]
Description=Lerim Memory Service
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username
Environment="OPENROUTER_API_KEY=sk-or-..."
ExecStart=/home/your-username/.local/bin/lerim serve
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable lerim
sudo systemctl start lerim
sudo systemctl status lerim

Replace /home/your-username/.local/bin/lerim with the output of which lerim.

Daemon intervals

The daemon runs two independent loops:

Sync interval: Default 10 minutes — indexes new sessions and extracts memories
Maintain interval: Default 60 minutes — merges duplicates, archives stale items

Configure in ~/.lerim/config.toml:

[daemon]
sync_interval_minutes = 10
maintain_interval_minutes = 60

Or override both uniformly:

lerim daemon --poll-seconds 300  # 5 minutes

Comparing workflows

Feature	Docker	Native
Setup	`lerim up`	`lerim serve`
Process isolation	Yes	No
Auto-restart	Yes (Docker restart policy)	No (manual or systemd)
Port binding	Configured in docker-compose	Configured in CLI flags
Logs	`lerim logs`	Stdout or manual redirection
Updates	Pull new image	`pip install --upgrade lerim`
Development	Requires rebuild	Instant edits with `-e`

Accessing the dashboard

With lerim serve running, open your browser:

http://localhost:8765

Or check the URL programmatically:

lerim dashboard
# Dashboard: http://localhost:8765
# The dashboard is served by `lerim serve` (or `lerim up` for Docker).

See the Dashboard guide for UI details.

Troubleshooting

Command not found: lerim

The lerim executable isn’t in your PATH.Solution: Ensure the Python bin directory is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Or activate your virtual environment:

source .venv/bin/activate

Port already in use

Another process is using port 8765.Solution: Use a different port:

lerim serve --port 9000

Or find and kill the conflicting process:

lsof -i :8765
kill <PID>

API key not found

Lerim can’t find an LLM provider API key.Solution: Export your API key in the current shell:

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

For persistent keys, add to ~/.bashrc, ~/.zshrc, or ~/.profile:

echo 'export OPENROUTER_API_KEY="sk-or-..."' >> ~/.bashrc
source ~/.bashrc

Daemon not syncing

Check that the daemon is actually running:

ps aux | grep lerim

Force a sync manually:

lerim sync

Verify connected platforms:

lerim connect list

Next steps

Query memories with lerim ask
Explore the dashboard interface
Switch to Docker workflow for production

Get Started

Core Concepts

Guides

Configuration

Native workflow

When to use native mode

Setup

Running the server

Custom host and port

Running the daemon manually

One-shot execution

Custom poll interval

Service commands

Local-only commands

Development workflow

Process management

Running in background

Systemd service

Daemon intervals

Comparing workflows

Accessing the dashboard

Troubleshooting

Next steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Configuration

​When to use native mode

​Setup

​Running the server

​Custom host and port

​Running the daemon manually

​One-shot execution

​Custom poll interval

​Service commands

​Local-only commands

​Development workflow

​Process management

​Running in background

​Systemd service

​Daemon intervals

​Comparing workflows

​Accessing the dashboard

​Troubleshooting

​Next steps

Build docs developers (and LLMs) love

When to use native mode

Setup

Running the server

Custom host and port

Running the daemon manually

One-shot execution

Custom poll interval

Service commands

Local-only commands

Development workflow

Process management

Running in background

Systemd service

Daemon intervals

Comparing workflows

Accessing the dashboard

Troubleshooting

Next steps