kirok-mcp 1.4.0__tar.gz

kirok_mcp-1.4.0/.env.example

@@ -0,0 +1,14 @@
+# Gemini API Key (required for embeddings and LLM operations)
+GEMINI_API_KEY=your-api-key-here
+
+# Database path (optional, defaults to ~/.kirok/memory.db)
+# KIROK_DB_PATH=~/.kirok/memory.db
+
+# Deduplication similarity threshold (optional, default: 0.85)
+# KIROK_DEDUP_THRESHOLD=0.85
+
+# Timeout for reflect operations in seconds (optional, default: 300)
+# KIROK_REFLECT_TIMEOUT=300
+
+# Timeout for consolidation operations in seconds (optional, default: 120)
+# KIROK_CONSOLIDATION_TIMEOUT=120

kirok_mcp-1.4.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: publish
+
+# Publish to PyPI via Trusted Publishing (OIDC) — no long-lived token stored
+# in the repo. Runs when a GitHub Release is published, or manually.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Run the offline test suite
+        run: |
+          uv sync
+          uv run --no-sync pytest -q
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kirok-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

kirok_mcp-1.4.0/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    # Tests run fully offline and need no GEMINI_API_KEY: importing
+    # kirok_mcp.server is side-effect-free (the key is checked at startup,
+    # not import) and tests swap in fake clients.
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        # setup-uv publishes no floating "v8" major tag (unlike v7 and earlier);
+        # pin the exact release.
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

kirok_mcp-1.4.0/.gitignore

@@ -0,0 +1,37 @@
+# Environment & Secrets
+.env
+.env.local
+.env.*.local
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# AI agent handoff files
+AI_HANDOFF.md
+
+# Internal planning/spec artifacts (kept local, not for downstream consumers)
+docs/superpowers/
+archive/

kirok_mcp-1.4.0/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to Kirok will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.4.0] - 2026-07-19
+
+### Fixed
+- **A consolidation LLM failure can no longer silently retire memories.** `LLMClient.consolidate` used to swallow every error (API failure after retries, unparseable response) and return an empty action list; the consolidation engine then marked the whole batch `consolidated_at` with zero observations produced and no failure recorded — those memories were permanently skipped. It now raises: the auto path records an `auto_consolidation` failure (visible in `KIROK_stats`) and leaves the batch pending for the next run; manual `KIROK_consolidate` reports the failure and records `manual_consolidation`
+- **Concurrent retains can no longer double-consolidate the same batch.** Two retains passing the debounce together could both read the same unconsolidated memories and produce near-duplicate observations. Consolidation is now serialized per bank with an `asyncio.Lock`; the second run re-reads the (now empty) pending set and exits
+- **The dedup merge and its audit event now commit as one transaction.** Previously the merged content committed first and the `memory_dedup_update` audit row (holding the pre-merge content) committed separately — a crash between the two persisted the merge with no recoverable trace of the original, violating the audit guarantee
+- A failure in the consolidation-debounce count query is now recorded to `system_events` (`consolidation_count`) instead of only being logged, matching every other background failure
+- `scripts/search_eval.py`: `--limit 5` no longer computes hit@5 twice, and `--limit 3` no longer prints a hit@5 column that was really hit@3; its docstring now states that it measures the memory fusion layer, not the full observation-aware recall reply
+
+### Changed
+- **Observations are now reachable by keyword.** The `fts_observations` index was written on every insert/update but never queried — consolidated knowledge was only findable through the semantic floor, so an observation whose cosine landed at e.g. 0.60 was invisible even on an exact keyword match. `KIROK_recall` now runs a keyword search (BM25 + short-CJK LIKE rescue, floor-exempt like the memory side) and fuses it with the semantic hits via RRF
+- **FTS text is NFKC-normalized on both the index and the query side**, so width variants now match: full-width ASCII (ＭＣＰ vs MCP) and half-width katakana (ﾊﾞｸﾞ vs バグ) were distinct code points that could never MATCH or LIKE each other. Existing databases rebuild their FTS tables once on the next startup (gated by `PRAGMA user_version`); source-table content is stored untouched
+- **RRF now fuses deeper candidate pools** (`max(limit*3, 30)` per source instead of `limit`): an item ranked just outside `limit` in both sources — a classic true hit that fusion exists to promote — was previously truncated out of both lists before RRF could see it
+- **The short-CJK LIKE rescue is now OR-joined across tokens**, matching the OR-joined FTS MATCH semantics. Previously it required every short token to appear (`京都 大阪` matched only rows containing both), while 3+ char queries used OR — an inconsistency that hid partial matches
+- `vec_search` no longer fetches and deserializes each hit's embedding BLOB (top_k × 3072 floats per call) — no consumer of its results reads it
+- New partial index `idx_memories_unconsolidated` makes the per-retain consolidation-debounce count and `get_unconsolidated_memories` index-only instead of scanning the bank's rows
+- `set_bank_config` uses an upsert (`ON CONFLICT DO UPDATE`) instead of SELECT-then-INSERT, removing a cross-process race on first config write
+- `KIROK_retain`'s dedup-UPDATE path now runs its re-extraction and re-embedding concurrently (`asyncio.gather`), like the ADD path already did
+
+### Removed
+- `MemoryDB.search_by_timestamp` — dead code since 1.3.0 made time-filtered recall filter FTS hits directly; nothing called it
+
+## [1.3.0] - 2026-07-10
+
+### Changed
+- **Short Japanese keyword queries now work**: 1-2 character kanji/katakana tokens (京都, 会議, バグ — below the trigram tokenizer's 3-char window, so they could never MATCH) are now served by an exact-substring LIKE supplement over the FTS text, appended after the BM25-ranked hits. Hiragana-only short tokens stay excluded (function words would substring-match half the bank). Previously these queries silently degraded hybrid search to semantic-only. The rescue now also runs whenever FTS already filled the results with 3+ char matches, instead of only when FTS came back short — a genuine short-token hit could otherwise be dropped
+- `KIROK_clear_bank` and `KIROK_delete_bank` now require `confirm=true`. Without it they change nothing and return a preview of what would be deleted — a single mistaken tool call can no longer wipe a bank
+- **FTS5 multi-word queries now use OR instead of implicit AND**: a document matching any query token is a hit, with BM25 naturally ranking documents that match more tokens higher — instead of requiring every token to match, which silently hid partial keyword overlaps
+- FTS hits now carry `timestamp` and `entities` (joined from `memories`), fixing the `[unknown]` placeholder that FTS-only recall results used to show and letting time-filtered recall filter FTS hits by their real timestamp directly, instead of intersecting with a separate `search_by_timestamp` call capped at `limit * 2` — which could silently drop in-range but relatively old FTS hits
+- RRF merging (`reciprocal_rank_fusion`) now merges matching items field-by-field instead of letting one list's dict fully overwrite the other's, so an FTS-only hit keeps its semantic metadata and vice versa
+- `vec_search`'s unused `candidate_multiplier` parameter is removed (per-bank KNN needs no over-fetch window; it stopped affecting results after the 1.1.0 per-bank partitioning)
+- `KIROK_retain`'s embedding and entity-extraction calls now run concurrently (`asyncio.gather`) instead of sequentially, cutting retain latency
+- `KIROK_recall` no longer lists an observation's own source memories under "Supporting Memories" — they were duplicated there and double-counted against `limit`
+- `kirok-doctor` gains an `--online` flag that adds one live embedding call to verify Gemini connectivity; default (offline) behavior is unchanged
+
+### Added
+- `scripts/search_eval.py` (+ `search_eval.example.json`): measures recall quality (hit@1/5/k, MRR) against a golden query set, through the exact recall pipeline the server uses (extracted as `hybrid_search_memories`). This is the yardstick for tuning search parameters — before it, no search change could be shown to help or hurt
+- SQLite connections now set `PRAGMA busy_timeout=30000` (30s), so concurrent MCP client instances wait out a busy writer instead of failing immediately with `database is locked`
+- Consolidation is now atomic: every create/update embedding is generated before any database write, and all observation changes plus `mark_memories_consolidated` commit as a single transaction. A failure (embedding or DB) leaves the database exactly as it was, with the source memories still unconsolidated for a later retry — instead of a partially-applied batch
+- Observations are now soft-deleted: consolidation's LLM-decided deletes stamp a new `observations.deprecated_at` column instead of removing the row (idempotent migration for existing databases). Deprecated observations are excluded from search, listing, and stats, but the row and an `observation_deprecated` audit event (in `system_events`) survive for recovery
+- Startup auto-snapshot: on server startup, a `VACUUM INTO` snapshot of the live database is taken to `~/.kirok/backups/memory-auto-*.db` if the newest existing auto-snapshot is older than `KIROK_AUTO_SNAPSHOT_HOURS` (default 24; `0` disables it), rotating to keep the newest `KIROK_SNAPSHOT_KEEP` (default 5). Only auto-snapshot files are ever rotated — manual `kirok-backup snapshot`/`export` files are untouched
+- A snapshot that fails partway (VACUUM INTO error or integrity check failure) no longer leaves a broken output file behind
+- JSON export/import now reads every table inside a single transaction (consistent cross-table snapshot even under concurrent WAL writers) and carries `deprecated_at` for observations; importing an older export without that field still works
+- A similarity floor for recall: `KIROK_RECALL_MIN_SIMILARITY` (default `0.62`) drops semantic (vector) memory hits below this cosine similarity, and `KIROK_OBS_MIN_SIMILARITY` (default `0.62`, replacing a hardcoded `0.4` that was below even off-topic scores) does the same for observations. FTS/keyword hits are exempt — a literal term match is independent evidence. 0.62 is calibrated on live `gemini-embedding-001` data: off-topic queries score 0.55-0.62 against unrelated banks, true hits score 0.66-0.73
+- Embedding calls now guard against dimension drift: a returned vector whose length doesn't match `EMBEDDING_DIM` (3072) raises `ValueError` instead of being silently stored
+- `KIROK_stats` now reports `API calls this session: embeddings=N, llm=M`, a session-lifetime counter on the embedding/LLM clients (resets on restart)
+- New offline tests: `test_llm_retry.py`, `test_search_eval.py`, `test_consolidation_atomicity.py`, `test_search_quality.py`, `test_stage3.py`, short-CJK rescue and confirm-guard cases
+
+### Fixed
+- `consolidate`, `evaluate_importance`, and `deduplicate` now actually retry transient Gemini failures (5xx/429/network). The 1.2.0 notes claimed all LLM calls retried, but these three fell straight to their fail-open defaults on a single transient error — e.g. a duplicate memory stored because deduplication "failed"
+- Deduplication's UPDATE path now records the pre-merge content as a `memory_dedup_update` audit event before overwriting it, so a bad LLM merge can be reconstructed instead of silently erasing the original memory
+- `observation_deprecated` and `memory_dedup_update` audit events no longer show up in `KIROK_stats`'s background-failure list — they are an audit trail, not failures, and were crowding out real background failures
+
+## [1.2.0] - 2026-07-03
+
+### Changed
+- Importing `kirok_mcp.server` is now side-effect-free: the database connection and Gemini clients are created at server startup (`main()`), and the `GEMINI_API_KEY` check moved from import time to startup — importing the module (tests, tooling) no longer opens the database or exits the process
+- CI no longer needs a dummy `GEMINI_API_KEY`
+- `db.py` (2000 lines) is now the `kirok_mcp.db` package, split by domain (schema, memories, search, observations, models, banks) and composed into the unchanged `MemoryDB` facade; the import surface is identical
+- The six copies of the vec-index sync (delete-then-insert with size guard) are consolidated into one `_sync_vec_row` helper
+- `KIROK_stats` now reports recent background failures (see Added)
+- Embedding and LLM calls now use the async Gemini client (`client.aio`) instead of blocking calls, so concurrent requests overlap and `KIROK_REFLECT_TIMEOUT` / `KIROK_CONSOLIDATION_TIMEOUT` actually take effect (they previously could not interrupt a blocking SDK call)
+- Auto-consolidation is now debounced: it runs once at least `KIROK_CONSOLIDATION_BATCH_SIZE` (default 5) memories are pending, instead of after every retain — cutting `KIROK_retain` latency and Gemini token usage. The consolidation report is no longer appended to the retain reply
+- `KIROK_recall` output is compact by default (content + ID only); pass `verbose=true` to include RRF/Sim relevance scores
+- **Japanese keyword search**: FTS5 now uses the `trigram` tokenizer instead of the default (which split CJK into single characters, leaving BM25 ineffective for Japanese). Existing databases rebuild their FTS index automatically on the next connect (rebuilt from the source tables, in a transaction that rolls back on failure). Queries shorter than 3 characters are served by semantic search instead (trigram cannot index them)
+- **Embeddings use asymmetric task types**: stored content uses `RETRIEVAL_DOCUMENT`, search queries use `RETRIEVAL_QUERY`, improving retrieval relevance. Dimension stays 3072 (pre-normalized). Existing data must be re-embedded once via `scripts/reembed.py` to gain the benefit
+- Observation recall now uses a per-bank sqlite-vec `vec0` KNN (`vec_observations`) with transparent brute-force fallback, mirroring memory search
+- Time-range `KIROK_recall` now filters by timestamp in SQL before scoring, instead of loading the whole bank into memory
+- `KIROK_stats` counts observations and unconsolidated memories via `COUNT(*)` (accurate beyond 1000 rows; previously capped)
+- `KIROK_update_memory` now re-extracts entities/keywords under the bank's `retain_mission`, consistent with the retain pipeline
+- Gemini embedding and LLM calls retry transient failures (5xx, 429, network) with bounded exponential backoff; structured errors (auth/bad-request) still fail fast
+- `semantic_search` is vectorized (single numpy matrix op) for faster brute-force/observation/time-range scoring
+
+### Added
+- Background failures (auto-consolidation, mental-model auto-refresh) are now recorded in a capped `system_events` table and surfaced by `KIROK_stats`, instead of being visible only in server logs
+- `kirok-backup` command: `snapshot` (verified `VACUUM INTO` copy of the live database), `export` (portable JSON of all banks, embeddings included), and `import` (transactional restore that skips existing IDs and rebuilds FTS/vector indexes). Fully offline — no API key required
+- `KIROK_CONSOLIDATION_BATCH_SIZE` environment variable (default 5) to tune auto-consolidation debouncing (set to 1 to restore per-retain consolidation)
+- `verbose` parameter on `KIROK_recall`
+- `MemoryDB.count_unconsolidated_memories` helper
+- `scripts/reembed.py`: idempotent, resumable re-embedding of all memories and observations (with `--dry-run`, backup-required gate, and a post-run integrity check)
+- `kirok-doctor` now checks that the sqlite-vec extension loads (the actual KNN backend), not just FTS5
+- `vec_observations` table plus `MemoryDB.vec_search_observations`, `get_embeddings_in_range`, `update_memory_embedding`, and `update_observation_embedding` helpers
+- New offline tests: `test_retry.py`, `test_fts_trigram.py`, `test_server_startup.py` (import is side-effect-free; missing API key fails at startup), and observation-vector / task-type / stats cases
+
+### Fixed
+- `KIROK_smart_retain` now honors `threshold` values below 5. Previously a hardcoded `score >= 5` floor in importance evaluation silently overrode lower thresholds, so `threshold=3` could never retain a score-3/4 item (e.g. a subtle preference)
+- `clear_bank`, `delete_bank`, `delete_observation`, and `clear_observations` now keep the observation vector index in sync
+
+## [1.1.0] - 2026-06-06
+
+### Added
+- Per-bank sqlite-vec `vec0` KNN for memory semantic search, with transparent fallback to brute-force cosine when the native extension is unavailable
+- `sqlite-vec` runtime dependency, an `EMBEDDING_DIM = 3072` constant, and a startup migration that backfills and reconciles the `vec_memories` table from stored embeddings
+- Offline setup diagnostics via the new `kirok-doctor` command
+- `auto_refresh` and `source_query` options for `KIROK_reflect` mental models
+- Test suite covering db, server, diagnostics, embeddings, and vector search (`test_vec_*`); `pytest` dev dependency
+
+### Changed
+- `KIROK_smart_retain` now routes through the shared retain pipeline
+- Bank clear/delete logic refactored to share a `_delete_bank_data` helper
+
+### Fixed
+- Clearing or deleting a bank now consistently removes its observations, FTS index rows, and bank configuration
+
+## [1.0.0] - 2026-04-09
+
+### Added
+- **Core Memory Operations**: Retain, Recall, Reflect — the three pillars of agent memory
+- **Smart Deduplication**: Mem0-inspired ADD/UPDATE/NOOP pipeline with configurable similarity threshold
+- **Hybrid Search**: Semantic (cosine similarity) + Keyword (FTS5 BM25) merged via Reciprocal Rank Fusion
+- **Observation Consolidation**: Autonomous pattern extraction from accumulated memories
+- **Mental Models**: LLM-generated insights with optional auto-refresh
+- **Smart Retain**: Importance-scored ingestion for bulk/automatic content
+- **Bank Configuration**: Per-bank retain and observations missions
+- **19 MCP tools**: Full CRUD for memories, mental models, observations, and bank management
+- **FTS5 query sanitization**: Safe handling of special characters in search queries
+- **MIT License**: Open-source under the MIT License

kirok_mcp-1.4.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to Kirok
+
+Thank you for your interest in contributing to Kirok! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+1. **Fork** the repository
+2. **Clone** your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/kirok-mcp.git
+   cd kirok-mcp
+   ```
+3. **Install** dependencies with [uv](https://docs.astral.sh/uv/):
+   ```bash
+   uv sync
+   ```
+4. **Set up** your environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env and add your GEMINI_API_KEY
+   ```
+
+## Development Workflow
+
+### Making Changes
+
+1. Create a new branch for your feature or fix:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+2. Make your changes in the `src/kirok_mcp/` directory
+3. Test your changes locally by running the MCP server
+4. Commit your changes with clear, descriptive messages
+
+### Code Style
+
+- **Python 3.12+** — use modern Python features (type hints, `|` union, etc.)
+- **Docstrings** — all public functions must have docstrings
+- **Logging** — use `logging.getLogger("kirok.module_name")` for all log output
+- **Error handling** — fail gracefully, never crash the MCP server
+
+### Running Tests
+
+Run the full test suite (unit tests plus the pytest-style vector-search tests) with:
+
+```bash
+uv run pytest
+```
+
+The `sqlite-vec` tests skip automatically on platforms where the native
+extension can't load — the brute-force fallback path is exercised separately.
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new tool for memory tagging
+fix: handle empty query in recall
+docs: update architecture diagram
+refactor: simplify deduplication logic
+```
+
+## Pull Requests
+
+1. Ensure your code follows the style guidelines above
+2. Update documentation if you've changed any public interfaces
+3. Add an entry to `CHANGELOG.md` under `[Unreleased]`
+4. Submit your PR with a clear description of the changes
+
+## Reporting Issues
+
+- Use GitHub Issues for bug reports and feature requests
+- Include your Python version, OS, and steps to reproduce
+
+## License
+
+By contributing to Kirok, you agree that your contributions will be licensed under the MIT License.

kirok_mcp-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tadahiro Fujikawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kirok_mcp-1.4.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: kirok-mcp
+Version: 1.4.0
+Summary: Persistent memory for AI agents — Retain, Recall, Reflect via MCP
+Project-URL: Homepage, https://github.com/TadFuji/kirok-mcp
+Project-URL: Repository, https://github.com/TadFuji/kirok-mcp
+Project-URL: Changelog, https://github.com/TadFuji/kirok-mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/TadFuji/kirok-mcp/issues
+Author: Tadahiro Fujikawa
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,embeddings,gemini,mcp,memory,semantic-search
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: sqlite-vec>=0.1.0
+Description-Content-Type: text/markdown
+
+# Kirok
+
+English | [日本語](README.ja.md)
+
+[![tests](https://github.com/TadFuji/kirok-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/TadFuji/kirok-mcp/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org)
+[![Version 1.4.0](https://img.shields.io/badge/version-1.4.0-blue.svg)](CHANGELOG.md)
+
+**Persistent memory for AI agents, over MCP.** Kirok (記録, "record") is a [Model Context Protocol](https://modelcontextprotocol.io) 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.
+
+## Why Kirok
+
+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:
+
+- **Hybrid retrieval, not just vectors.** Semantic KNN and FTS5 BM25 are fused with Reciprocal Rank Fusion, so an exact keyword match and a semantic match reinforce each other instead of competing.
+- **A calibrated relevance floor.** Naive cosine thresholds don't work on real embedding distributions (see [Search quality](#-search-quality)); Kirok's floor is measured against live data, and there's an evaluation harness to keep it honest.
+- **Autonomous consolidation.** Memories are periodically synthesised into observations, and destructive LLM decisions are soft-deleted with an audit trail rather than executed blindly.
+- **Reliability first.** Atomic writes, soft deletes, startup auto-snapshots, and a fail-open background pipeline that never loses a `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).
+
+## Architecture
+
+```mermaid
+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](docs/architecture.md) for the full design.
+
+## 🚀 Quick start
+
+**Requirements:** Python 3.12+, [uv](https://docs.astral.sh/uv/), and a [Gemini API key](https://aistudio.google.com/apikey) (free tier is plenty).
+
+```bash
+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
+```
+
+### Connect an MCP client
+
+**Claude Desktop** — edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "kirok": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/kirok-mcp", "kirok-mcp"]
+    }
+  }
+}
+```
+
+**Claude Code CLI:**
+
+```bash
+claude mcp add kirok -s user -- uv run --directory /absolute/path/to/kirok-mcp kirok-mcp
+```
+
+Then restart the client. `GEMINI_API_KEY` is read from `.env`, so it need not go in the config.
+
+> [!TIP]
+> **If `uv run` fails to launch the server** (common on Windows or cloud-synced folders — `uv run` re-syncs on every launch and can hit locked `.venv` files or an in-use entry-point `.exe`), invoke the venv's Python directly to skip the sync entirely:
+>
+> ```json
+> {
+>   "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.exe` and double-backslash paths in JSON.
+
+A bundled agent skill in [`skills/kirok/`](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.
+
+## 🛠️ Tools
+
+19 MCP tools. One-line summaries below; full parameter tables in [docs/tools-reference.md](docs/tools-reference.md).
+
+**Core**
+
+| Tool | Purpose |
+|------|---------|
+| `KIROK_retain` | Store a memory: entity/keyword extraction + embedding + smart ADD/UPDATE/NOOP dedup |
+| `KIROK_recall` | Hybrid semantic + keyword search (RRF), observations shown first |
+| `KIROK_reflect` | Synthesise memories into a mental model (insight), optionally auto-refreshing |
+| `KIROK_smart_retain` | Score importance (1–10) first, then retain only if it clears a threshold |
+| `KIROK_consolidate` | Manually run observation consolidation for a bank |
+
+**Memory management**
+
+| Tool | Purpose |
+|------|---------|
+| `KIROK_get_memory` / `KIROK_list_memories` | Fetch one memory / browse a bank with pagination |
+| `KIROK_update_memory` | Edit content or context (re-extracts and re-embeds on content change) |
+| `KIROK_forget` | Delete a single memory (irreversible) |
+
+**Mental models**
+
+| Tool | Purpose |
+|------|---------|
+| `KIROK_list_mental_models` / `KIROK_get_mental_model` | List / inspect insights from Reflect |
+| `KIROK_refresh_mental_model` | Re-analyse against current memories |
+| `KIROK_delete_mental_model` | Delete a mental model (irreversible) |
+
+**Banks**
+
+| Tool | Purpose |
+|------|---------|
+| `KIROK_list_banks` / `KIROK_stats` | List banks with counts / detailed per-bank stats incl. background failures |
+| `KIROK_clear_bank` | Delete a bank's memories + observations (requires `confirm=true`; previews otherwise) |
+| `KIROK_delete_bank` | Delete a bank entirely (requires `confirm=true`; previews otherwise) |
+
+**Config**
+
+| Tool | Purpose |
+|------|---------|
+| `KIROK_set_bank_config` / `KIROK_get_bank_config` | Set / view a bank's retain & observation "missions" (what to focus on) |
+
+## ⚙️ Configuration
+
+Everything is set via environment variables (typically in `.env`). Only `GEMINI_API_KEY` is required.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GEMINI_API_KEY` | — | **Required.** Google Gemini API key. |
+| `KIROK_DB_PATH` | `~/.kirok/memory.db` | SQLite database location. |
+| `KIROK_DEDUP_THRESHOLD` | `0.85` | Cosine similarity above which retain invokes the LLM dedup (ADD/UPDATE/NOOP) decision. |
+| `KIROK_RECALL_MIN_SIMILARITY` | `0.62` | Similarity floor for semantic memory hits in recall. Keyword/FTS hits are exempt. |
+| `KIROK_OBS_MIN_SIMILARITY` | `0.62` | Similarity floor for observation hits in recall. |
+| `KIROK_CONSOLIDATION_BATCH_SIZE` | `5` | Run auto-consolidation only once this many memories are pending (`1` = every retain). |
+| `KIROK_CONSOLIDATION_TIMEOUT` | `120` | Consolidation timeout, seconds. |
+| `KIROK_REFLECT_TIMEOUT` | `300` | Reflect timeout, seconds. |
+| `KIROK_AUTO_SNAPSHOT_HOURS` | `24` | Min hours between startup auto-snapshots (`0` disables). |
+| `KIROK_SNAPSHOT_KEEP` | `5` | Auto-snapshot generations to keep before rotating out the oldest. |
+
+## 🔍 Search quality
+
+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 (ＭＣＰ 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`](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:
+
+```bash
+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
+```
+
+## 🛡️ Reliability
+
+- **Atomic consolidation.** Every create/update embedding is generated *before* any DB write; all observation changes plus the "consolidated" mark commit in a single transaction. A failure at any step leaves the database exactly as it was, with the source memories still pending for a later retry — never a half-applied batch.
+- **Failures surface, never fake success.** A consolidation LLM failure raises and is recorded to `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.
+- **Soft deletes with audit trail.** An observation the consolidation LLM decides to remove is stamped `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.
+- **Startup auto-snapshot.** On launch, if the newest auto-snapshot is older than `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.
+- **Concurrency.** Connections set `PRAGMA busy_timeout=30000`, so a second MCP client waits out a busy writer instead of failing with `database is locked`.
+- **Fail-open background work.** Auto-consolidation and mental-model refresh run behind `retain` and can never fail it — errors are swallowed, recorded to `system_events`, and surfaced via `KIROK_stats` so silent degradation stays visible.
+
+## 💾 Backup & restore
+
+All state is one SQLite file. The offline `kirok-backup` CLI needs no API key:
+
+```bash
+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.
+
+## 🩺 Diagnostics
+
+```bash
+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
+```
+
+## 🧑‍💻 Development
+
+```bash
+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](.github/workflows/test.yml)). See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
+
+## 📚 Documentation
+
+- [docs/architecture.md](docs/architecture.md) — internal design, data model, consolidation engine
+- [docs/tools-reference.md](docs/tools-reference.md) — full parameter reference for all 19 tools
+- [CHANGELOG.md](CHANGELOG.md) — version history (current: 1.4.0)
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).
+
+## Acknowledgements
+
+- [Model Context Protocol](https://modelcontextprotocol.io) and the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (FastMCP)
+- [Google Gemini API](https://ai.google.dev/) for embeddings and LLM
+- [Mem0](https://github.com/mem0ai/mem0) — inspiration for smart deduplication and the knowledge layer
+- [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) (Cormack et al., 2009)