llre

AI-native structured memory for agents — a project memory that AI agents read and write directly (lore/doc), via MCP.

A FastMCP server (stdio) that plugs into any MCP client. As the AI works, it records lore (decisions, pitfalls, local rules) and doc (specs, system docs) directly, searches them next session, and detects drift against your code. Humans set direction and approve — tell the AI, and the AI records.

Built for agents, not humans — every tool here is designed for usability by an AI, not readability for a person.

한국어 · localized docs at linklore.io/docs

Fastest way to install: tell your agent

This is an MCP server — it's meant to be set up by an AI agent, not typed in by hand. Paste this as your first message to Claude Code, Cursor, or any other MCP-capable agent:

Set up LinkLore (an MCP server for project memory) in this repo. It's the PyPI package llre, run via uvx llre — no install or clone needed. Register it as an MCP server for whichever client you are (Claude Code: claude mcp add llre -- uvx llre; otherwise add {"mcpServers": {"llre": {"command": "uvx", "args": ["llre"]}}} to this project's .mcp.json), then run uvx llre init here. Ask me first before running uvx llre login — it opens a browser for Google login and is only needed for personal backup or team sharing. Once it's set up, follow the CLAUDE.md section it adds: call brief() at the start of every session and record decisions as lore.

Prefer to type the commands yourself? See Install / run below.

Why

AI agents forget decisions when the session ends. Spec files keep the conclusion but lose the why. LinkLore keeps the judgment itself as lore, so the next session's AI picks it up with a single brief().

$ uvx llre                                              # runs immediately — no setup

# The AI records a decision while working
add(type='lore', title='Retry capped at 3', msg='API misclassifies 5xx as 429 — infinite retry risk, cap at 3')
→ [lr-8a21f0] Retry capped at 3

# Next session — new conversation, same project
brief()
→ Recent: [lore] Retry capped at 3 — API misclassifies 5xx as... [lr-8a21f0]

Full introduction and screenshots: linklore.io/docs.

Mental model

• lore (lr-) — decisions, pitfalls, local rules, footprints. status open/done/rule.
• doc (dc-) — specs and system docs. group for category, items for checklists/catalogs.
• lore↔doc bidirectional links (link) + file anchors → automatic code context (stale detection, show(file=...)).

Install / run

Standard install — PyPI package llre (runs via uvx, no clone needed):

uvx llre init          # set up .linklore in this directory (start the project memory)
uvx llre               # MCP server for AI tools (stdio, no args)
uvx llre login         # Google login (browser) — auth for personal backup / team sharing

Embedding search is an optional extra: uvx --from 'llre[embed]' llre (fastembed + numpy).

Platforms: macOS (Apple Silicon), Linux (x86_64), Windows (x86_64) — Python 3.11+.

Claude Code

claude mcp add llre -- uvx llre

Other MCP clients

Project .mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "llre": {
      "command": "uvx",
      "args": ["llre"]
    }
  }
}

Logs go to ~/.linklore/mcp.log.

CLI

Besides the MCP stdio server (uvx llre, no args), every tool is callable directly from the terminal — one set of tool functions, two entrances (MCP/CLI).

Seven commands humans type by hand:

uvx llre init            # set up .linklore in this directory
uvx llre login           # Google login (browser)
uvx llre logout          # remove local token
uvx llre connect         # link this project to my account (personal backup)
uvx llre whoami          # show my identity (read-only)
uvx llre doctor          # project data integrity check
uvx llre report <msg>    # file feedback/bugs directly (no login required)

All 23 registered tools are also callable through the generic dispatcher — uvx llre <tool> [key=value ...]:

uvx llre brief
uvx llre show query=lr-x
uvx llre add type=lore title=Title msg=Body

Argument values are parsed as JSON first — max=5 becomes an int, help=true a bool; anything that fails to parse stays a string.

Tools (23)

Tool arguments prefer lists (tags=['a','b']). Each tool documents itself with help=True.

Data layout

.linklore/
├── model/
│   └── settings.json        # project settings
├── system/
│   ├── linklore.db          # single SQLite home — lore/doc/links/history
│   ├── embeddings.npz       # lore embeddings (+ embed_index.json)
│   ├── embed_doc.npz        # doc embeddings (+ embed_doc_index.json)
│   ├── codemap.json         # code map cache
│   └── versions/            # version snapshots
├── remote/                  # server/openbox local cache + identity (not the store)
│   ├── personal/            # personal server (push/pull) connection info
│   └── <project-id>/        # per-openbox received cache (meta.json + lore/doc)
└── external/
    └── registry.json        # external source registry

• The home store is a single SQL source (linklore.db, WAL mode). Your data is a local file that is yours to inspect, back up, and delete.
• LINKLORE_DB_URL can point at Postgres or another DB (SQLite by default).

Source model

Mostly readable, core compiled. The published wheel ships the entry point, i18n catalogs, base utilities, and the onboarding guide as readable Python; the core modules (search, ranking, contradiction detection, tool logic) ship as compiled extensions. The readable portion is published at the project repository. We'd rather be upfront that the crown-jewel logic is compiled than pretend the package is fully open.

Environment variables

License

Elastic License 2.0 — free to install and use; you may not provide the software as a competing managed service, circumvent license-key functionality, or remove licensing notices.

Team sync, cross-project sharing, and cloud backup are provided by the backend service at linklore.io.