lorecards

English · 中文

A keyword-triggered card book for companion agents. One card per person, event, place, thing or in-joke the user has mentioned — plain Markdown with YAML frontmatter, in a folder they own. When the conversation mentions a card's keywords (anywhere in the last few turns, not just the current message), the card is written into the prompt before the model sees it. So the second time a friend or a running saga comes up, the AI already knows who is who, and nobody has to write a "previously on…" recap.

Surfacing is not something the model has to remember to do. A proxy in front of your API, or a hook in Claude Code, injects the card — the same way a world-info system does. And because a card that fires every turn would be paid for every turn, each conversation keeps a small ledger and the same card is not injected again for a few turns. See Dedupe.

It is not RAG and not a memory store. Nothing is embedded, scored by similarity, or written behind the user's back. A card book is canon: what the user (or the agent, through the write_card tool) decided is worth remembering, in a file they can read, edit and delete.

~/cards/
  people/Alice.md
  events/the Friday deploy.md
  places/the corner cafe.md
  things/the blue notebook.md
  slang/ship it Friday.md

Install

Installs straight from GitHub — no PyPI package needed. Pick one:

pipx install 'lorecards-mcp[zh] @ git+https://github.com/tsuru0805/lorecards-mcp'
uv tool install 'lorecards-mcp[zh] @ git+https://github.com/tsuru0805/lorecards-mcp'
pip install 'lorecards-mcp[zh] @ git+https://github.com/tsuru0805/lorecards-mcp'   # into any venv

([zh] pulls in the jieba segmenter for Chinese and Japanese; drop it if you only write in spaced languages. The pip line is the one verified in a clean venv; the other two are the standard pipx / uv syntax for a git source.) Or install from source.

lorecards init ~/cards            # the directories, plus one example card per kind

Then pick how cards reach your model. The three ways are independent.

1. The gateway (recommended)

A proxy that sits in front of your API and injects cards into the prompt. Works with any client that lets you set a base URL: SillyTavern, Kelivo, PWAs, SwiftUI apps, your own scripts — nothing has to know lorecards exists.

lorecards gateway --vault ~/cards --upstream https://api.openai.com
#   -> base URL for your client: http://127.0.0.1:8765/v1

Then in your client, change the API base URL from https://api.openai.com/v1 to http://127.0.0.1:8765/v1 and leave everything else alone — your key still goes straight to the upstream, unchanged and unlogged.

• SillyTavern: API Connections → Chat Completion → Custom (OpenAI-compatible) → Custom Endpoint http://127.0.0.1:8765/v1. Your API key stays in the same field it was in.

• Kelivo (and most mobile clients): Settings → Providers → the provider's API base URL → http://127.0.0.1:8765/v1. On a phone, use the computer's LAN address instead of 127.0.0.1 and start the gateway with --host 0.0.0.0.

Both protocols are handled, streaming included: POST /v1/chat/completions (OpenAI-compatible) and POST /v1/messages (Anthropic Messages). Every other path is proxied untouched.

$ curl -s http://127.0.0.1:8765/v1/chat/completions -D- \
    -H 'Authorization: Bearer sk-…' -H 'Content-Type: application/json' \
    -d '{"model":"gpt-4o","messages":[{"role":"user","content":"how did the friday deploy go?"}]}'
x-lorecards-injected: the Friday deploy
…
# what the upstream received as the last user message
# (the marker's suffix is a per-process nonce, so it differs on every run):
# <!-- lorecards:9fef39 -->
# A memory surfaces:
#
# ### the Friday deploy [event]
# ## when
# Every Friday afternoon, since the team moved to weekly releases.
# …
# <!-- /lorecards:9fef39 -->
#
# how did the friday deploy go?

From a phone, the gateway must listen beyond localhost, and then a token is required — otherwise anyone on the network could spend your API key:

lorecards gateway --vault ~/cards --upstream https://api.openai.com \
  --host 0.0.0.0 --token "$(openssl rand -hex 16)"

The client then has to send X-Lorecards-Token: <that token> — a separate header, so it never collides with the Authorization your client sends to the upstream. In a client that lets you add custom headers (SillyTavern does), add it there. --host 0.0.0.0 without --token refuses to start.

Injected text is wrapped in <!-- lorecards:… --> markers (the suffix is a per-process nonce, so we only ever strip our own), which are stripped out again when the next turn is scanned — otherwise a card would keep itself alive by quoting its own keywords. If anything on our side fails (unreadable vault, odd body shape), the request is forwarded unchanged: the proxy never stands between you and your model.

2. The Claude Code hook

Same idea, inside Claude Code — every turn, no tool call. In .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "lorecards hook --vault ~/cards", "timeout": 10 }
        ]
      }
    ]
  }
}

lorecards hook reads the hook JSON on stdin (user_prompt, plus transcript_path for the recent turns) and answers with hookSpecificOutput.additionalContext. It exits 0 and prints nothing when no card matches, and it never blocks a prompt. One Claude Code session is one conversation for dedupe purposes, keyed on session_id. (Hook contract per the Claude Code docs, checked 2026-09-13.)

3. The MCP server — for writing cards

claude mcp add lorecards -- lorecards-mcp --vault ~/cards

{
  "mcpServers": {
    "lorecards": { "command": "lorecards-mcp", "args": ["--vault", "/Users/you/cards"] }
  }
}

Three tools: write_card, read_card, list_cards. This is how an agent writes down what it just learned — mode="create" for a new card, mode="update_recent" to refresh only the "recent" section of one that exists.

There is deliberately no recall tool. A model that has to decide to look something up mostly does not, and world-info systems work precisely because the surfacing is not the model's job. Recall belongs to the gateway or the hook.

lorecards-mcp speaks stdio by default; --http serves streamable HTTP instead. It runs on both the 1.x and 2.x mcp SDK.

From source

git clone https://github.com/tsuru0805/lorecards-mcp && cd lorecards-mcp
python3 -m venv .venv && .venv/bin/pip install -e '.[zh]'
.venv/bin/lorecards ui --vault ~/cards

For Chinese (or any language without spaces between words), install the [zh] extra for jieba segmentation.

Related MCP server: Knowledge Base MCP Server

Web UI

Writing YAML by hand gets old. There is an editor:

lorecards ui --vault ~/cards          # -> http://localhost:8766

One page: cards by kind on the left, a form built from your actual section table on the right, a "try a sentence" box at the top that shows what would surface and offers unused proper nouns as one-click keywords, and collapsible recently surfaced and health check panels. Import and export SillyTavern lorebooks from the same page. It works on a phone in portrait, ships a web manifest so it can be added to the home screen, and loads no external resources at all.

From your phone, on the same Wi-Fi:

lorecards ui --vault ~/cards --host 0.0.0.0 --token "$(openssl rand -hex 16)"
# open http://<your computer's LAN address>:8766/?token=<that token>

--host anything other than localhost requires --token, which the API then checks as Authorization: Bearer <token> (the ?token= in the link is stored by the page, wiped from the address bar, and sent as that header afterwards). On localhost there is no token at all: anyone who can reach the port can edit the vault.

Against the other browser tab, /api/* is guarded even without a token: the Host header must be one this server actually serves (so a rebound name cannot reach it), a request whose Origin is a different site is refused, and every write must carry X-Lorecards: 1 — a header a cross-site form cannot add without a preflight, which we never answer. Static files stay open; they hold no card data.

HTTP API

The UI is only one client. Everything it does is a documented endpoint, so a PWA, a SwiftUI app or a shell script can do the same. All errors are {"error": code, "detail": message}.

Writes (POST / PUT / DELETE) must send X-Lorecards: 1, and a request carrying an Origin from another site is refused. With --token, add Authorization: Bearer <token>.

mtime is a string: it is nanosecond-resolution and would lose precision as a JSON number in a browser, which would break every optimistic-locking check.

Card format

~/cards/people/Alice.md:

---
kind: people
title: Alice
keywords: [Alice, payments team]
aliases: [Al]
secondary:
  not: [Alice Cooper]
scan_depth: 3
refs: [Bob]
priority: 1
---
## who
Alice — works on the payments team, sits two desks away.

## stance
Friendly. She reviews my pull requests and I review hers.

## recent
Took over the refund flow rewrite in September.

## impression
Direct, allergic to meetings that could have been a message.

The directory decides the kind; kind: in the frontmatter is only a copy. Sections per kind:

Headings you add that are not in the table are kept verbatim, never dropped. Frontmatter is parsed forgivingly: keywords: Alice, Bob works as well as a proper list, and a malformed value falls back to the default instead of breaking the card.

Private sections

Some things belong on the card but must never reach a model — working notes, a draft, the backing material for a letter. Any section named in private_sections (default: correspondence) stays in the file, is readable through read_card and editable in the UI (labelled never injected), and is cut out of everything the engine matches on or injects. Words in there cannot even make the card fire.

kinds.yaml

Directory and section names are configurable, so a vault can be written in another language. Put a kinds.yaml in the vault root:

dirs:     { people: personnes, event: evenements }
sections: { people: [qui, relation, recent, impression] }
recent_section: { people: recent }
private_sections: [correspondance]

How matching works

Chinese, Japanese and other unspaced text are segmented with jieba when the [zh] extra is installed. Without it, matching falls back to substring search plus whitespace/punctuation tokens: multi-character terms still work, single-character ones mostly will not.

Dedupe

A card that matches on five turns in a row would otherwise be injected five times — five times the tokens, for something already sitting in the context window. So:

• A conversation is identified by the X-Lorecards-Conversation request header when the client sends one, and otherwise by sha256(system prompt + first user message)[:16]. In Claude Code, it is the hook's session_id.

• A turn index is how many user messages the request carries (the hook, which has no request to count, keeps its own counter).

• A card injected at turn n is skipped until turn n + --reinject-after (default 6). Once it falls out of that window, a fresh match injects it again.

• The ledger lives at <vault>/.lorecards/injections.json, written atomically, capped at 200 cards per conversation and 500 conversations (least-recently-seen dropped first).

• The response carries X-Lorecards-Injected: key1,key2 when anything was injected, which is the quickest way to see what is happening.

• If the ledger cannot be read, it is rebuilt empty and the request still goes through.

• A turn index that goes backwards (the client trimmed its history) is treated as a new clock rather than a reason to stay silent forever.

• Read-modify-write is done under a file lock, so two gateways sharing one vault do not overwrite each other.

--reinject-after 0 turns dedupe off and injects on every match.

What gets written to disk

Your API key and the model's replies are never stored or logged. Two files under <vault>/.lorecards/ are:

--no-log on lorecards gateway, lorecards hook or lorecards ui skips hits.jsonl entirely (on ui it also overrides /api/try?log=1); dedupe still works, since that lives in the other file. Delete either file at any time.

Import / export (SillyTavern lorebooks)

lorecards import book.json --vault ~/cards          # existing cards are kept
lorecards import book.json --vault ~/cards --force  # overwrite them
lorecards export out.json --vault ~/cards

Known mapping limits

• constant (always-on entries) is not supported — a card fires on keywords or not at all. The flag is preserved on export; it does nothing while the card is in this book.

• 3 NOT ALL is approximated by not, which vetoes when any of the words appears. SillyTavern only vetoes when all of them do, so an imported NOT ALL entry is stricter here.

• scanDepth counts messages in SillyTavern and turns here, so it is halved on import and doubled on export; odd values round up.

• position, probability, depth (insertion depth), group, role and recursion settings have no equivalent — they are carried through, not honoured.

• Import puts everything in one kind (--kind, default entry); sorting a book into people/events/places is a manual pass afterwards.

Pairing with a penpal mail system

If your companion writes actual letters, a people card is a good place to keep the address book, because it is already the thing that knows who someone is. Two conventions:

---
kind: people
title: Alice
keywords: [Alice]
emails: [alice@example.com]          # a simple card
ais:                                 # …or one card covering several personas
  - name: Aria
    emails: [aria@example.com, aria.work@example.com]
---
## who
Alice — works on the payments team.

## correspondence
Last letter went out on the 3rd; she asked about the refund rewrite.
Draft: answer the rewrite question, ask about the reading group.

• The emails: / ais[].emails lists are the single source of truth for the send whitelist — if an address is not on a card, nothing may write to it. Keeping it here means the whitelist is edited in the same place as the relationship it belongs to.

• ## correspondence is a private section: the model reading the card never sees it, and the mail system reads it deliberately when drafting a reply. That is what keeps a long correspondence from growing into the prompt without bound.

The design this comes from is written up here (in Chinese): AI 笔友系统：一套不会无限膨胀的长期通信记忆方案.

CLI

lorecards gateway --upstream URL  the injecting proxy (see Install)
lorecards ui                      the web editor + HTTP API
lorecards try "sentence"          which cards fire, why, and what deserves a card
  --turns '[{"role":"user","text":"..."}]'   --show-context   --json
lorecards list [--kind people]    every card with its keywords
lorecards read Alice              print one card
lorecards check                   cards that can never fire, or fire far too often
lorecards init ~/cards            create the vault with one example card per kind
lorecards import book.json        SillyTavern lorebook in
lorecards export out.json         SillyTavern lorebook out
lorecards hook                    the Claude Code UserPromptSubmit hook

  gateway: --token, --no-log, --inject, --window, --reinject-after, --budget, --framing
  ui:      --token, --no-log, --host, --port
  hook:    --reinject-after, --no-log, --budget, --scan-depth

--vault works on either side of the subcommand, and falls back to $LORECARDS_VAULT, then ~/.lorecards.

Known limits

• Matching is keywords, not meaning. "my sister" does not find the card titled Rin unless my sister is one of its keywords or aliases. That is the trade: it is predictable, auditable, and costs no embedding pass.

• The gateway must be able to read the request body, so it only injects into JSON chat requests it recognises. Anything else is a plain proxy.

• Dedupe is per conversation as identified above. A client that rotates its system prompt on every request, and sends no X-Lorecards-Conversation header, will look like a new conversation each time.

• The UI has no users and no roles. One vault, one editor, no audit trail; on localhost, no authentication at all. It is a tool for the person whose cards they are.

• One vault per process. Several characters or profiles means several gateways or several entries in your MCP config, one --vault each.

• The injection markers carry a nonce that is new on every start, so a block written before a restart is no longer recognised as ours and stays in the history it was written into. It is inert text; it is only scanned as if the user had typed it.

• The dedupe ledger is a single JSON file per vault, rewritten whole under a lock. That is fine for one person's conversations; it is not built for dozens of concurrent writers.

• Cards are cached on file mtime and size, so an edit takes effect on the next lookup — but a change that keeps both identical will not be noticed.

• No pagination: a very large book still loads every card into memory at lookup time.

Author

• 晚晚 (@tsuru0805) — design, decisions, real-world acceptance.

• 弥野 (Claude, 晚晚's engineering hand) — implementation and docs.

Extracted (clean-room) from the card book that runs in the tilldusk home system.

MIT licensed. Built from a card system running in a private companion-agent setup, rewritten clean for general use.