Kirok
English | 日本語
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
uvx kirok-mcp==1.4.2Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
GEMINI_API_KEY=<secret> claude mcp add io.github.tadfuji-kirok-mcp -- uvx kirok-mcp==1.4.2รันในเทอร์มินัล
{ "mcpServers": { "io.github.tadfuji-kirok-mcp": { "command": "uvx", "args": [ "kirok-mcp==1.4.2" ], "env": { "GEMINI_API_KEY": "<secret>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
English | 日本語
Persistent memory for AI agents - hybrid semantic + keyword recall with autonomous consolidation
Persistent memory for AI agents, over MCP. Kirok (記録, "record") is a Model Context Protocol server that gives an agent a durable, searchable memory: Retain what matters, Recall it with hybrid semantic + keyword search, and Reflect to distil accumulated memories into reusable insights. A background consolidation loop turns raw memories into higher-level observations on its own.
Most "agent memory" is either a flat vector store (recall is a bare cosine top-k, no keyword grounding, no forgetting) or a pile of markdown the agent has to re-read every turn. Kirok is a small, self-hostable server that does the retrieval engineering properly:
retain.Not local-first: storage is a local SQLite file you own, but embedding and LLM inference are sent to Google's Gemini API. If everything must stay on-device, Kirok is not for you (yet).
flowchart TB
client["MCP Client<br/>(Claude Desktop / Claude Code / Cursor / …)"]
subgraph server["Kirok MCP Server (FastMCP)"]
direction TB
tools["19 MCP tools<br/>Retain · Recall · Reflect · consolidate · CRUD"]
pipeline["Hybrid search (RRF) · Smart dedup<br/>Consolidation · Auto-refresh"]
end
subgraph storage["Local SQLite (WAL)"]
direction LR
fts["FTS5 trigram<br/>(BM25 keyword)"]
vec["sqlite-vec<br/>(KNN, brute-force fallback)"]
tables["memories · observations<br/>mental_models · banks · system_events"]
end
gemini["Google Gemini API<br/>gemini-embedding-001 (3072-d)<br/>gemini-2.5-flash-lite"]
client <-->|"stdio (JSON-RPC 2.0)"| tools
tools --> pipeline
pipeline <--> storage
pipeline <-->|embeddings · entity extraction<br/>reflection · consolidation| gemini
Storage is a single SQLite database at ~/.kirok/memory.db. sqlite-vec provides per-bank vector KNN; if the native extension can't load, Kirok falls back to a NumPy brute-force scan with identical results. See docs/architecture.md for the full design.
Requirements: Python 3.12+, uv (for uvx), and a Gemini API key (free tier is plenty).
Kirok ships on PyPI — nothing to clone. Put your key in ~/.kirok/.env (one line: GEMINI_API_KEY=AIza...), then verify the setup:
uvx --from kirok-mcp kirok-doctor # offline sanity check
Claude Code CLI:
claude mcp add kirok -s user -- uvx kirok-mcp
Claude Desktop — edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"kirok": { "command": "uvx", "args": ["kirok-mcp"] }
}
}
Then restart the client. The server reads GEMINI_API_KEY from ~/.kirok/.env; an env block in the client config also works and takes precedence.
git clone https://github.com/TadFuji/kirok-mcp.git
cd kirok-mcp
uv sync # installs deps, including sqlite-vec
cp .env.example .env # then put your key in it: GEMINI_API_KEY=AIza...
uv run kirok-doctor # offline sanity check of the whole setup
Point your MCP client at the checkout with uv run --directory /absolute/path/to/kirok-mcp kirok-mcp instead of uvx kirok-mcp.
[!TIP] If
uv runfails to launch the server (common on Windows or cloud-synced folders —uv runre-syncs on every launch and can hit locked.venvfiles or an in-use entry-point.exe), invoke the venv's Python directly to skip the sync entirely:{ "mcpServers": { "kirok": { "command": "/absolute/path/to/kirok-mcp/.venv/bin/python", "args": ["-m", "kirok_mcp.server"], "env": { "PYTHONPATH": "/absolute/path/to/kirok-mcp/src" } } } }On Windows use
.venv\\Scripts\\python.exeand double-backslash paths in JSON.
A bundled agent skill in skills/kirok/ teaches the agent when and how to use the memory tools on its own — point your client at skills/kirok/SKILL.md to enable it.
19 MCP tools. One-line summaries below; full parameter tables in docs/tools-reference.md.
Core
Memory management
Mental models
Banks
Config
Everything is set via environment variables (typically in .env). Only GEMINI_API_KEY is required.
Recall runs semantic KNN and FTS5 BM25 in parallel and fuses them with Reciprocal Rank Fusion (k=60). Short Japanese keyword queries get special handling: 1–2 character kanji/katakana tokens fall below the trigram tokenizer's 3-char window and can never MATCH, so they're rescued by an exact-substring LIKE supplement appended after the BM25 hits (hiragana-only short tokens stay excluded — function words would substring-match half a bank; tokens are OR-joined, matching the MATCH side).
Three details keep the hybrid honest: each source is fetched deeper than the final page (max(limit*3, 30)) so RRF can promote an item ranked just outside the cut in both lists; all FTS text is NFKC-normalized on both the index and query side, so width variants (MCP vs MCP, バグ vs バグ) actually match; and observations get the same hybrid treatment as memories — semantic hits floored, keyword hits floor-exempt — instead of being reachable only through the semantic floor.
The similarity floor is calibrated on real data. A naive cosine threshold doesn't work here: on live gemini-embedding-001 vectors the distribution is narrow — off-topic queries score 0.55–0.62 against unrelated banks while true hits score 0.66–0.73. So the usable floor sits just above the off-topic ceiling, at 0.62. Without it, an unrelated query still returns a full page of memories from any non-empty bank (context pollution); much lower and the floor filters nothing (the old hardcoded 0.4 sat below even off-topic scores). FTS keyword hits bypass the floor entirely — a literal term match is independent evidence, not a weak vector score.
Search parameters aren't tuned by vibes. scripts/search_eval.py runs a golden query set through the exact recall pipeline the server uses (extracted as hybrid_search_memories, so the harness can't drift from production) and reports hit@1/hit@5/hit@k and MRR:
cp scripts/search_eval.example.json my_golden.json # add 30–50 real cases
uv run python scripts/search_eval.py my_golden.json --limit 10
system_events — the batch stays pending for a later retry, instead of being silently marked consolidated with nothing produced. Runs are serialized per bank, so two retains landing together cannot double-process the same batch into duplicate observations.deprecated_at (excluded from search/list/stats) instead of destroyed, and a dedup UPDATE records the pre-merge content in the same transaction as the merge itself — both logged to system_events so a bad LLM decision is recoverable, not silent data loss.KIROK_AUTO_SNAPSHOT_HOURS, a VACUUM INTO + integrity_check snapshot is written under ~/.kirok/backups/, keeping the newest KIROK_SNAPSHOT_KEEP generations. A snapshot that fails partway leaves no broken file behind, and manual backups are never rotated.PRAGMA busy_timeout=30000, so a second MCP client waits out a busy writer instead of failing with database is locked.retain and can never fail it — errors are swallowed, recorded to system_events, and surfaced via KIROK_stats so silent degradation stays visible.All state is one SQLite file. The offline kirok-backup CLI needs no API key:
uv run kirok-backup snapshot # byte-level DB copy (safe while server runs)
uv run kirok-backup export # portable JSON of all banks + memories + observations + models
uv run kirok-backup import ~/.kirok/backups/kirok-export-YYYYMMDD-HHMMSS.json
snapshot and export write timestamped files under ~/.kirok/backups/ and refuse to overwrite. import runs in one transaction (all-or-nothing), skips existing IDs rather than overwriting, and rebuilds the FTS + vector indexes so search works immediately. Use --db to target a different database file.
uv run kirok-doctor # offline: Python version, .env, key presence (never printed),
# required modules, FTS5, sqlite-vec, DB writability
uv run kirok-doctor --json # machine-readable, for automation
uv run kirok-doctor --online # adds one live embedding call to verify Gemini connectivity
uv sync
uv run --no-sync pytest # 164 offline tests; no API key or network needed
The suite is fully offline — importing kirok_mcp.server is side-effect-free (the API key is checked at startup, not import) and tests swap in fake Gemini clients. CI runs the same suite on Ubuntu and Windows on every push (.github/workflows/test.yml). See CONTRIBUTING.md before opening a PR.
MIT — see LICENSE.
Persistent memory for AI agents - hybrid semantic + keyword recall with autonomous consolidation
{ "mcpServers": { "io.github.tadfuji-kirok-mcp": { "command": "uvx", "args": [ "kirok-mcp==1.4.2" ], "env": { "GEMINI_API_KEY": "<secret>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: GEMINI_API_KEY
Kirok Memory ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-09 Persistent memory for AI agents - hybrid semantic + keyword recall with autonomous consolidation