lorecards-mcp
Gateway proxy sits in front of OpenAI-compatible APIs, injecting matching lore cards into chat completion requests while forwarding other paths untouched.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lorecards-mcp write a card for Alice, my teammate from the Friday deploy"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.mdInstall
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 kindThen 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/v1Then 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 of127.0.0.1and 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?flag | default | what it does |
| required | the API this sits in front of |
|
| where the proxy listens |
|
|
|
|
| turns of history scanned for keywords |
|
| turns before the same card may be injected again ( |
|
| characters of cards per injection |
|
| the line that introduces the cards |
| — | require |
| off | do not record what surfaced in the hit ledger |
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 ~/cardsFor Chinese (or any language without spaces between words), install the [zh] extra for
jieba segmentation.
Related MCP server: memex
Web UI
Writing YAML by hand gets old. There is an editor:
lorecards ui --vault ~/cards # -> http://localhost:8766One 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}.
method | path | what it does |
|
| section table, directory names, private sections — build your form from this, do not hard-code section names |
|
| list: key, kind, title, keywords, aliases, enabled, inject, preview, mtime |
|
| one card: every frontmatter key, |
|
| create; |
|
| update; send back the |
|
| move to |
|
| bring it back |
|
| dry run: which cards fire, on which words, in or out of budget, plus candidate keywords. Add |
|
| what surfaced lately, from the gateway, the hook and logged tries |
|
| cards with no keywords, keywords too generic to be useful, titles that do not match the file name |
|
|
|
|
| the vault as a SillyTavern lorebook |
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:
kind | directory | sections |
people |
| who · stance · recent · impression |
event |
| when · who · what · stance · followup |
place |
| where · relation · recent |
thing |
| what · usage · recent |
slang |
| meaning · origin · usage |
entry | vault root | free-form |
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
Match terms |
|
Window | the current message + the last |
Substring vs token | terms of 2+ characters may match inside a word; 1-character terms must match a whole token, so a single-character keyword does not fire on every word containing it |
| every listed word must appear somewhere in the window |
| at least one must appear in the window |
| checked only in the messages that produced the hit, so an excluded word three turns back does not veto a card the user just named |
| one level deep: a referenced card contributes one line ("who is this"), not its whole body — and nothing if it already fired on its own |
Score | number of distinct terms hit, plus one per term hit in the current message |
Order | score ↓, then |
Budget | 800 characters by default. The top card always gets in even if it is over budget; the first card that would overflow stops the list, and the rest are reported as |
| never loaded. |
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-Conversationrequest header when the client sends one, and otherwise bysha256(system prompt + first user message)[:16]. In Claude Code, it is the hook'ssession_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,key2when 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:
file | what is in it |
| per conversation: which card keys were injected, at which turn, and when it was last seen. No message text. |
| one line per surfacing: timestamp, source ( |
--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 ~/cardsSillyTavern | card |
|
|
|
|
|
|
| card body |
|
|
|
|
|
|
everything else ( | kept verbatim under |
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 ALLis approximated bynot, 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.scanDepthcounts 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,roleand recursion settings have no equivalent — they are carried through, not honoured.Import puts everything in one kind (
--kind, defaultentry); 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[].emailslists 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.## correspondenceis 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
Rinunlessmy sisteris 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-Conversationheader, 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
--vaulteach.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.
Available Tools
3 toolslist_cardsA
List every card in the book, optionally of one kind (people, event, place, thing, slang, entry).
Inputs: kind. Returns: object
read_cardA
Read one whole card by key (its file name without .md).
Inputs: key (required). Returns: object
write_cardA
Write a card.
kind: people | event | place | thing | slang | entry. key: the card's file name, also its default title. fields: section name -> text. people: who/stance/recent/impression; event: when/who/what/stance/followup; place: where/relation/recent; thing: what/usage/recent; slang: meaning/origin/usage; entry: {"_head": "..."}. keywords: what the card listens for. aliases: other ways the subject gets named. refs: keys of other cards worth one line of context when this one fires. mode="create" refuses to overwrite an existing card; mode="update_recent" rewrites only the recent section (followup for events) of a card that already exists.
Inputs: key (required), kind (required), fields (required), mode, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
list_cards, read_card, and write_card map cleanly onto list/read/write with no overlap. The only internal branching is write_card's mode parameter (create vs update_recent), which is explicitly documented rather than a separate ambiguous tool.
All three names follow a strict verb_noun snake_case pattern (list_cards, read_card, write_card). The verbs are distinct and predictable, with no mixed conventions or casing anomalies.
Three tools is lean but defensible for a card store, since write_card's mode parameter absorbs both creation and partial updates. It sits at the lower edge of comfortable scope, with no obvious redundancy.
The surface covers list/read/write but has no delete or remove operation, leaving cards unremovable once written. There is also no search-by-keyword tool, even though keywords and aliases are first-class fields, forcing agents to list everything and filter client-side.
Maintenance
Related MCP Connectors
A living memory and world-building layer for your AI: cards, worlds, personas and agent dispatch.
Build and study spaced-repetition flashcards with your agent.
Read-only access to Penwright's writing-craft book library, grounded guide metadata (card-level...
Markdown notes and whiteboards your AI agent can read and write.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to persistently store, recall, link, and sync atomic markdown knowledge cards across sessions and supported clients without a vector database.9 npmISC
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to save and recall atomic markdown knowledge cards with bidirectional links across sessions, so learning persists and builds over time. Cards live as plain, git-syncable files readable by both agent and human, with no vector database or embeddings required.9 npmISC
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents and users to store, search, read, link, organize, sync, and browse atomic markdown knowledge cards across sessions and clients without a vector database.9 npmISC
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to keep persistent, Zettelkasten-style memory by saving and recalling atomic markdown knowledge cards with bidirectional links across sessions. Supports searching, reading, writing, linking, organizing, and git-syncing those cards through a set of MCP tools, with no vector database required.9 npmISC