llre 0.2.0

AI-native structured memory for agents — lore/doc that AI agents read and write directly (MCP)

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.

한국어 · 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. level 1–4 (importance), status open/done.
• 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 22 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 — level=2 becomes an int, help=true a bool; anything that fails to parse stays a string.

Tools (22)

Category	Tool	Description
Setup	init	Initialize project data (creates .linklore/, blueprint supported)
Project	brief	Project dashboard — call at the start of every session
Project	status	Code↔doc sync state (stale detection, ack)
Project	config	Project settings + external source management
Diagnostics	doctor	Data integrity check (id/paths/link targets), action='fix' auto-repairs
Diagnostics	report	File feedback/bugs to the team — anonymous allowed, works with or without login
Record	add	Add lore/doc (type='lore'|'doc', batch when items=dict list)
Record	edit	Edit an entry — msg= always appends
Record	rm	Delete — trash (soft) by default, force=True for permanent
Record	restore	Restore from trash. Without id, lists the trash
Record	local	Operate on other workspaces on the same disk — action='move'|'copy'|'show'
Query	show	Search/browse — query, type, tag, level, status, file, period filters
Query	log	Change history
Link	link	Connect two entries — dc↔dc / lr↔lr / dc↔lr automatically
Link	unlink	Disconnect (symmetric to link)
Doc views	doc_flow	Render a doc flowLink chain in order (journey view)
Doc views	doc_map	Bird's-eye view of the whole doc link network
Doc views	doc_rollup	Collect lore linked to a doc → draft for AI summarization
Cleanup	cleanup	Detect duplicate-lore candidates (similarity threshold)
My server	push	Personal backup to backend (think git remote)
My server	pull	Personal restore (symmetric to push)
Openbox	openbox	One gate for shared team boxes — share/bring in/browse (action='push'|'pull'|'show' …) + membership governance (invite/join/docking/role …)

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

Variable	Description
LINKLORE_BACKEND_URL	backend API base. Default https://api.linklore.io
LINKLORE_DB_URL	DB URL override. Default: SQLite .linklore/system/linklore.db
LINKLORE_LANG	Tool output language (en, ko). Defaults to OS locale, falls back to en
CLAUDE_PROJECT_DIR	Project-root anchor injected by MCP client hooks

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.