Metadata-Version: 2.4
Name: llre
Version: 0.1.0
Summary: AI-native coding memory — lore/doc that AI agents read and write directly (MCP)
Author: LinkLore
License: Copyright (c) 2026 LinkLore (support@linklore.io)
        
        Elastic License 2.0
        
        URL: https://www.elastic.co/licensing/elastic-license
        
        ## Acceptance
        
        By using the software, you agree to all of the terms and conditions below.
        
        ## Copyright License
        
        The licensor grants you a non-exclusive, royalty-free, worldwide,
        non-sublicensable, non-transferable license to use, copy, distribute, make
        available, and prepare derivative works of the software, in each case subject to
        the limitations and conditions below.
        
        ## Limitations
        
        You may not provide the software to third parties as a hosted or managed
        service, where the service provides users with access to any substantial set of
        the features or functionality of the software.
        
        You may not move, change, disable, or circumvent the license key functionality
        in the software, and you may not remove or obscure any functionality in the
        software that is protected by the license key.
        
        You may not alter, remove, or obscure any licensing, copyright, or other notices
        of the licensor in the software. Any use of the licensor’s trademarks is subject
        to applicable law.
        
        ## Patents
        
        The licensor grants you a license, under any patent claims the licensor can
        license, or becomes able to license, to make, have made, use, sell, offer for
        sale, import and have imported the software, in each case subject to the
        limitations and conditions in this license. This license does not cover any
        patent claims that you cause to be infringed by modifications or additions to
        the software. If you or your company make any written claim that the software
        infringes or contributes to infringement of any patent, your patent license for
        the software granted under these terms ends immediately. If your company makes
        such a claim, your patent license ends immediately for work on behalf of your
        company.
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part of the software from you
        also gets a copy of these terms.
        
        If you modify the software, you must include in any modified copies of the
        software prominent notices stating that you have modified the software.
        
        ## No Other Rights
        
        These terms do not imply any licenses other than those expressly granted in
        these terms.
        
        ## Termination
        
        If you use the software in violation of these terms, such use is not licensed,
        and your licenses will automatically terminate. If the licensor provides you
        with a notice of your violation, and you cease all violation of this license no
        later than 30 days after you receive that notice, your licenses will be
        reinstated retroactively. However, if you violate these terms after such
        reinstatement, any additional violation of these terms will cause your licenses
        to terminate automatically and permanently.
        
        ## No Liability
        
        *As far as the law allows, the software comes as is, without any warranty or
        condition, and the licensor will not be liable to you for any damages arising
        out of these terms or the use or nature of the software, under any kind of
        legal claim.*
        
        ## Definitions
        
        The **licensor** is the entity offering these terms, and the **software** is the
        software the licensor makes available under these terms, including any portion
        of it.
        
        **you** refers to the individual or entity agreeing to these terms.
        
        **your company** is any legal entity, sole proprietorship, or other kind of
        organization that you work for, plus all organizations that have control over,
        are under the control of, or are under common control with that
        organization. **control** means ownership of substantially all the assets of an
        entity, or the power to direct its management and policies by vote, contract, or
        otherwise. Control can be direct or indirect.
        
        **your licenses** are all the licenses granted to you for the software under
        these terms.
        
        **use** means anything you do with the software requiring one of your licenses.
        
        **trademark** means trademarks, service marks, and similar rights.
        
Project-URL: Homepage, https://linklore.io
Project-URL: Documentation, https://api.linklore.io/docs
Keywords: mcp,linklore,spec,ai,claude,cursor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Documentation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: sqlalchemy>=2.0
Provides-Extra: remote
Requires-Dist: uvicorn>=0.30.0; extra == "remote"
Requires-Dist: starlette>=0.38.0; extra == "remote"
Provides-Extra: embed
Requires-Dist: fastembed>=0.4.0; extra == "embed"
Requires-Dist: numpy>=1.24.0; extra == "embed"
Dynamic: license-file

# llre

**AI-native coding memory** — a project memory that AI agents read and write directly (lore/doc), via [MCP](https://modelcontextprotocol.io).

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.

[한국어](./README.ko.md) · localized docs at [linklore.io/docs](https://linklore.io/docs.html)

## 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](#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](https://linklore.io/docs.html).

## 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):

```bash
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

```bash
claude mcp add llre -- uvx llre
```

### Other MCP clients

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

```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:

```bash
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>    # send feedback/bugs directly (no login required)
```

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

```bash
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 (24)

| 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` | Send 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 | `send` | Send entries to an openbox |
| Openbox | `import` | Import from an openbox into the project |
| Openbox | `member` | Member/role governance (new/invite/join …) |

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](./LICENSE) — 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](https://linklore.io).
