Lorekeeper

Lorekeeper

Self-improving memory for AI agents. One command, no cloud, no config.

> ```bash

> pip install lorekeeper-mcp && lorekeeper setup && lorekeeper

> ```

>

> Your agent remembers across sessions — and the memory gets better, not just bigger.

> Local. No API keys. No sign-up. Free to run forever.

Why Lorekeeper

Every AI agent session starts blank. You re-explain context, re-state preferences, re-teach patterns — every single time.

Files like `CLAUDE.md` and `.cursorrules` help, but they're hand-maintained, can't search themselves, and grow stale. Cloud services work, but your session data leaves your machine and you're paying per API call. Libraries are powerful, but you're writing the integration yourself.

Lorekeeper is a different shape: a local MCP server you `pip install` once. It connects to your existing agents, stores memories in SQLite on your own disk, and starts improving with every session:

Agent uses a memory → rates it useful or not →
scores adjust automatically → weak memories decay →
strong memories surface more often → search gets sharper

A fresh install and a six-month-old install are genuinely different products. The longer you use it, the less noise you get — and the more your agents feel like they actually know your codebase.

Quick Start

3 minutes, zero configuration:

# 1. Install
pip install lorekeeper-mcp

# 2. Configure your agents (auto-detects Hermes, Claude Code, Cursor)
lorekeeper setup

# 3. Start the MCP server
lorekeeper

`lorekeeper setup` scans for installed agents and injects the MCP entry, agent prompt, and bundled skills automatically. Use `--check` to preview without writing. Run `lorekeeper --help` or `lorekeeper --version` to verify the install.

Then ask your agent:

> _"Remember that I prefer `curl -vX GET` for debugging endpoints."_

It calls `lore_remember` → memory stored. Next session:

> _"What's my preferred debug command?"_

It calls `lore_search` → memory retrieved. ✅

**Full walkthrough → docs/quickstart.md**

Features

MCP Tools

Lorekeeper exposes 10 MCP tools covering the full memory lifecycle:

**Full API reference → docs/api-reference.md**

Dashboard

A local web UI to browse, search, edit, and manage your memory store.

lorekeeper-dashboard
# → http://127.0.0.1:7777

Seven tabs:

Suggestions Tab

The Suggestions tab surfaces link candidates generated automatically by the background sweep engine. Each candidate is a pair of memories the engine considers related, scored by cosine similarity, BM25 keyword overlap, entity co-occurrence, and temporal proximity.

Workflow:

1. The sweep engine runs on a configurable interval (`LORE_SUGGEST_INTERVAL_HOURS`, default `12`).

2. Candidates appear in the Suggestions tab, sorted by score (highest first).

3. Click ✓ (or select multiple rows + Accept Selected) to create a permanent link between the two memories.

4. Click ✗ (or Reject Selected) to dismiss — rejected pairs are never re-surfaced by future sweeps.

5. Use Trigger Sweep on the Config tab to run the sweep immediately instead of waiting for the interval.

Sweep configuration (via `LORE_`-prefixed env vars or the Config tab):

Built by Agents, For Agents

Lorekeeper is developed _using_ AI agents — Claude Code, Hermes, and our own agent team. The development cycle is itself a working demo of what it does:

agent builds a feature → uses Lorekeeper to capture what it learned →
searches those memories next session →
builds the next feature with the context already there

This isn't a marketing line. Every tool schema, return type, and workflow in Lorekeeper was shaped by agents using it daily — not by humans reading specs. When something was annoying to use, we changed it. When search returned noise, we tuned the weights. The product is what it is because the agents that build it depend on it.

> The agentic development loop documented in this repo is how we actually work — and it's what Lorekeeper is designed to support for you.

For Developers

Clone, run from source, or contribute:

git clone https://github.com/Jessinra/Lorekeeper.git
cd Lorekeeper
bash scripts/setup.sh

# Tests
uv run pytest

# Lint
uv run ruff check src tests

# Type check
uv run mypy src

# Dashboard dev
uv sync --extra dashboard
uv run lorekeeper-dashboard

Project Layout

src/lorekeeper/
├── __main__.py          # Entrypoint — init_service() + mcp.run(stdio)
├── server.py            # FastMCP tool definitions (8 tools)
├── config.py            # Settings (pydantic-settings, LORE_ prefix)
├── models.py            # Pydantic models
├── dashboard/           # Web UI (FastAPI + uvicorn)
└── services/
    ├── orchestrator.py  # MemoryService — coordinates sub-services
    ├── memory_engine.py # Vector store abstraction
    ├── lancedb_engine.py# LanceDB backend
    ├── link_store.py    # SQLite — memories, links, suggestions
    ├── keyword_index.py # BM25 index
    ├── search.py        # Hybrid ranking
    └── ...

Key Configuration

All settings via `LORE_`-prefixed env vars or the dashboard Config tab:

Full list → `src/lorekeeper/config.py` and `CLAUDE.md`.

Performance

All 500 LongMemEval-S questions, default hybrid weights (sem=0.45, kw=0.30):

Full per-category breakdown → docs/research/2026-06-11-retrieval-benchmark-results.md

License

Apache-2.0 — see LICENSE.

_Built by agents, for agents._ Manifesto · Strategy

_Last verified: 2026-06-20_