MCP 服务器

Kirok

Provides persistent, searchable memory for AI agents, enabling them to retain, recall, and reflect on information across conversations.

README

📝 Kirok

Persistent Memory for AI Agents

Retain knowledge. Recall with precision. Reflect for deeper insights.

🇬🇧 English | 🇯🇵 日本語はこちら

</div>

Kirok (記録, "record" in Japanese) is a Model Context Protocol (MCP) server that gives AI agents persistent, searchable memory. Without Kirok, your AI assistant forgets everything when you start a new conversation. With Kirok, it remembers your preferences, past decisions, lessons learned, and can even generate insights from accumulated knowledge.

✨ What Can Kirok Do?

Feature	What It Means
🧠 Retain	Your AI stores information and automatically extracts key details
🔍 Recall	Your AI searches past memories using both meaning and keywords
💡 Reflect	Your AI analyzes accumulated memories to generate insights
🔄 Smart Dedup	Automatically avoids storing duplicate information
📊 Observations	Detects patterns across your memories over time
🎯 Bank Missions	Customize what each memory bank focuses on

🎁 Bonus: Core "Kirok" Agent Skill Included

To help your AI understand and use its new memory capabilities automatically, we've bundled the core "kirok" Agent Skill inside the skills/ directory.

kirok: Teaches the AI how to use Kirok's memory mechanics effectively. Instead of having to tell the AI "remember this", the AI will automatically know when and how to store context.

How to use (Quick Start):

Copy the skills folder into your working directory.
In your very first chat, just tell the AI: "Please read skills/kirok/SKILL.md and follow its instructions." (Pro Tip: You can add this sentence to your Custom Instructions / System Prompt so the AI reads it automatically every time you start a new conversation!)

🚀 Getting Started (Step by Step)

Follow these steps in order. Estimated time: 10–15 minutes.

Step 1: Install Python 3.12+

Kirok requires Python 3.12 or newer.

The easiest way is using Homebrew:

# Install Homebrew (if you don't have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.12

Verify the installation:

python3 --version
# Should show: Python 3.12.x or newer

</details>

<details> <summary>🪟 Windows</summary>

Go to python.org/downloads
Download the latest Python 3.12+ installer
Important: Check the box ✅ "Add Python to PATH" during installation
Click "Install Now"

Verify the installation by opening PowerShell and running:

python --version
# Should show: Python 3.12.x or newer

</details>

Step 2: Install uv (Python Package Manager)

uv is a fast Python package manager that Kirok uses.

curl -LsSf https://astral.sh/uv/install.sh | sh

Then restart your terminal, and verify:

uv --version

</details>

<details> <summary>🪟 Windows</summary>

Open PowerShell and run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then close and reopen PowerShell, and verify:

uv --version

</details>

Step 3: Get a Gemini API Key (Free)

Kirok uses Google's Gemini AI for understanding and searching your memories. The free tier is more than enough for personal use.

Go to Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy the key (it starts with AIza...) — you'll need it in Step 5

💡 Tip: The free tier allows 1,500 requests per day — plenty for normal use.

Step 4: Download and Install Kirok

# Choose where to install (e.g., your home directory)
cd ~

# Download Kirok
git clone https://github.com/TadFuji/kirok-mcp.git
cd kirok-mcp

# Install dependencies
uv sync

</details>

<details> <summary>🪟 Windows</summary>

# Choose where to install (e.g., your Desktop)
cd $env:USERPROFILE\Desktop

# Download Kirok
git clone https://github.com/TadFuji/kirok-mcp.git
cd kirok-mcp

# Install dependencies
uv sync

Don't have Git? Download it from git-scm.com first.
Alternatively, download Kirok as a ZIP from the GitHub page → green "Code" button → "Download ZIP", then unzip it.

</details>

Note: uv sync also installs sqlite-vec, which speeds up memory search. If the native extension can't load on your platform, Kirok automatically falls back to built-in brute-force search — same results, just slower.

Step 5: Configure Your API Key

cp .env.example .env

Open the .env file in any text editor and replace your-api-key-here with the API key you copied in Step 3:

GEMINI_API_KEY=AIzaSy...your-key-here...

</details>

<details> <summary>🪟 Windows</summary>

Copy-Item .env.example .env

Open the .env file in Notepad (or any text editor) and replace your-api-key-here with the API key you copied in Step 3:

GEMINI_API_KEY=AIzaSy...your-key-here...

</details>

Step 6: Connect to Claude Desktop

Now connect Kirok to your AI client. The most common setup is Claude Desktop.

Find the config file

OS	Config file location
🍎 Mac	`~/Library/Application Support/Claude/claude_desktop_config.json`
🪟 Windows	`%APPDATA%\Claude\claude_desktop_config.json`

💡 How to open the config file: In Claude Desktop, go to Settings (gear icon) → Developer → Edit Config. If the option doesn't appear, create the file manually at the path above.

Add Kirok to the config

Open the config file and add the Kirok server. Replace /path/to/kirok-mcp with the actual folder path where you installed Kirok.

<details> <summary>🍎 Mac example</summary>

{
  "mcpServers": {
    "kirok": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/Users/yourname/kirok-mcp",
        "kirok-mcp"
      ]
    }
  }
}

Replace /Users/yourname/kirok-mcp with your actual path.

</details>

<details> <summary>🪟 Windows example</summary>

{
  "mcpServers": {
    "kirok": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "C:\\Users\\YourName\\Desktop\\kirok-mcp",
        "kirok-mcp"
      ]
    }
  }
}

Replace C:\\Users\\YourName\\Desktop\\kirok-mcp with your actual path.
Important: Use double backslashes \\ in JSON on Windows.

</details>

<details> <summary>📌 Already have other MCP servers?</summary>

If your config file already has other servers, just add the kirok entry inside the existing mcpServers object:

{
  "mcpServers": {
    "existing-server": {
      "...": "..."
    },
    "kirok": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/kirok-mcp",
        "kirok-mcp"
      ]
    }
  }
}

</details>

Restart Claude Desktop

After saving the config file, completely quit and restart Claude Desktop. Kirok should now appear in the MCP tools list.

Step 7: Verify It Works

In a new Claude Desktop conversation, try asking:

"Use Kirok to remember that my favorite programming language is Python."

Claude should use the KIROK_retain tool to store this memory. Then in a new conversation, ask:

"What's my favorite programming language?"

If Claude recalls "Python" using KIROK_recall, everything is working! 🎉

🔧 Other MCP Clients

<details> <summary>Gemini CLI / Antigravity</summary>

Add to your mcp_config.json:

{
  "mcpServers": {
    "kirok": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/kirok-mcp",
        "kirok-mcp"
      ]
    }
  }
}

</details>

<details> <summary>VS Code / Cursor</summary>

Add to your workspace or user MCP settings (.vscode/mcp.json or VS Code settings):

{
  "mcpServers": {
    "kirok": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/kirok-mcp",
        "kirok-mcp"
      ]
    }
  }
}

</details>

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│                  MCP Client                      │
│       (Claude Desktop, Cursor, etc.)             │
└──────────────────────┬──────────────────────────┘
                       │ MCP Protocol (stdio)
┌──────────────────────▼──────────────────────────┐
│              Kirok MCP Server                    │
│  ┌───────────┐  ┌──────────┐  ┌──────────────┐  │
│  │  19 Tools │  │ LLM      │  │ Embedding    │  │
│  │  (CRUD)   │  │ Client   │  │ Client       │  │
│  └─────┬─────┘  └────┬─────┘  └──────┬───────┘  │
│        │             │               │           │
│  ┌─────▼─────────────▼───────────────▼───────┐   │
│  │         SQLite + FTS5 + sqlite-vec         │   │
│  │  memories │ models │ observations │ config │   │
│  └────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────┘
                       │
          ┌────────────▼────────────┐
          │    Google Gemini API    │
          │  gemini-embedding-001   │
          │  gemini-2.5-flash-lite  │
          └─────────────────────────┘

📖 Tools Reference

Kirok provides 19 MCP tools organized into five categories:

Core Operations

Tool	Description
`KIROK_retain`	Store a memory with automatic entity extraction, embedding, and smart deduplication
`KIROK_recall`	Search memories using hybrid semantic + keyword search with RRF
`KIROK_reflect`	Generate insights from accumulated memories, saved as optionally auto-refreshing mental models
`KIROK_smart_retain`	Score content importance before running the full retain pipeline — ideal for bulk ingestion
`KIROK_consolidate`	Manually trigger observation consolidation

Memory Management

Tool	Description
`KIROK_get_memory`	Get full details of a specific memory
`KIROK_update_memory`	Update content/context of an existing memory
`KIROK_forget`	Delete a specific memory (irreversible)
`KIROK_list_memories`	Browse memories with pagination

Mental Models

Tool	Description
`KIROK_list_mental_models`	List insights generated by Reflect
`KIROK_get_mental_model`	Get full details of a mental model
`KIROK_delete_mental_model`	Delete a mental model (irreversible)
`KIROK_refresh_mental_model`	Re-analyze with latest memories

Bank Management

Tool	Description
`KIROK_list_banks`	List all memory banks with counts
`KIROK_stats`	Get detailed statistics for a bank
`KIROK_clear_bank`	Delete all memories and observations in a bank
`KIROK_delete_bank`	Permanently delete a bank and all its data

Configuration

Tool	Description
`KIROK_set_bank_config`	Set retain/observations missions for a bank
`KIROK_get_bank_config`	View current bank configuration

⚙️ Configuration

All configuration is via environment variables in the .env file:

Variable	Required	Default	Description
`GEMINI_API_KEY`	✅	—	Google Gemini API key (get one free)
`KIROK_DB_PATH`	❌	`~/.kirok/memory.db`	Custom database path
`KIROK_DEDUP_THRESHOLD`	❌	`0.85`	Similarity threshold for deduplication (0.0–1.0)
`KIROK_REFLECT_TIMEOUT`	❌	`300`	Timeout in seconds for reflect operations
`KIROK_CONSOLIDATION_TIMEOUT`	❌	`120`	Timeout in seconds for consolidation
`KIROK_CONSOLIDATION_BATCH_SIZE`	❌	`5`	Run auto-consolidation only once this many memories are pending (set `1` to consolidate on every retain)

🩺 Diagnostics

Run the offline setup checker:

uv run kirok-doctor

It checks Python version, .env loading, GEMINI_API_KEY presence (without printing the key), required Python modules, SQLite FTS5 support, the sqlite-vec extension (the KNN backend), and database directory writability. It does not call Gemini or any network API.

JSON output is available for automation:

uv run kirok-doctor --json

If your local environment cannot run the script entry point, use the module form:

uv run python -m kirok_mcp.diagnostics

💾 Backup & Restore

All memories live in a single SQLite file, so back it up regularly with the offline kirok-backup command (no API key needed):

# Byte-level copy of the database (safe while the server is running)
uv run kirok-backup snapshot

# Portable JSON export of all banks (memories, observations, models, configs)
uv run kirok-backup export

# Restore from a JSON export — existing IDs are skipped, never overwritten
uv run kirok-backup import ~/.kirok/backups/kirok-export-20260610-081853.json

Both snapshot and export default to timestamped files under ~/.kirok/backups/ and refuse to overwrite existing files. import runs in a single transaction (all-or-nothing) and rebuilds the FTS and vector indexes, so search works immediately on the restored data. Use --db to target a different database file (e.g. restoring into a fresh one).

🧪 How It Works

The Retain → Recall → Reflect Loop

Retain: When you store a memory, Kirok:
- Generates a semantic embedding via gemini-embedding-001
- Extracts entities and keywords via gemini-2.5-flash-lite
- Checks for duplicates using cosine similarity (> 0.85 threshold)
- If similar memories exist: decides to ADD, UPDATE existing, or SKIP
- Indexes in both SQLite and FTS5 for hybrid search
- Auto-consolidates observations once enough memories are pending (debounced by KIROK_CONSOLIDATION_BATCH_SIZE, default 5)
Smart Retain first asks the LLM to score content importance (1-10). If the score meets the threshold, it runs this same Retain pipeline — including deduplication, UPDATE/NOOP decisions, indexing, and auto-consolidation.
Recall: When you search, Kirok:
- Runs semantic search (sqlite-vec per-bank vector KNN, with automatic brute-force fallback)
- Runs keyword search (FTS5 with BM25 ranking)
- Merges results using Reciprocal Rank Fusion (RRF, k=60)
- Shows consolidated observations first, then supporting memories
- Returns a compact result by default (content + ID); pass verbose=true for relevance scores
Reflect: When you reflect, Kirok:
- Retrieves relevant memories via semantic search
- Sends them to the LLM with existing mental models as context
- Saves the resulting insight as a new mental model
- Can mark that model for auto-refresh after future consolidation

Memory Banks

Memories are organized into banks — think of them as folders for your AI's memory:

"work" — Work-related decisions and learnings
"personal" — Personal preferences and habits
"projects" — Project-specific knowledge

Create as many banks as you need. Your AI agent will suggest appropriate bank names as you use Kirok.

🧑‍💻 Development

Run the test suite (pytest is the standard runner; it also collects the unittest-style test classes):

uv run pytest

The tests cover the SQLite database layer, FTS query handling, bank clearing and deletion consistency, embedding utilities, Smart Retain's routing through the shared Retain pipeline, Reflect auto-refresh options, backup/export/import roundtrips, the background-failure log, and offline diagnostics. They do not call Gemini or any external API. The same suite runs in CI on every push (.github/workflows/test.yml, Ubuntu and Windows).

❓ Troubleshooting

<details> <summary>"uv: command not found" or "'uv' is not recognized"</summary>

uv is not installed or not in your PATH.

Run the uv installation command again from Step 2
Close and reopen your terminal / PowerShell after installation
On Mac, you may need to restart your shell: source ~/.zshrc

</details>

<details> <summary>Not sure what's wrong with your setup?</summary>

Run:

uv run kirok-doctor

If that command itself fails because your environment is mid-upgrade or a local script is locked, try:

uv run python -m kirok_mcp.diagnostics

The diagnostic output is offline and safe to share after checking paths; it never prints your Gemini API key.

</details>

<details> <summary>"Python 3.12+ is required" or version mismatch</summary>

Check your Python version:

python3 --version   # Mac
python --version    # Windows

If it shows an older version, install Python 3.12+ from Step 1.

On Mac with multiple Python versions, uv will automatically find the right one. On Windows, uninstall older versions or adjust your PATH.

</details>

<details> <summary>Kirok doesn't appear in Claude Desktop</summary>

Make sure you completely quit Claude Desktop (not just close the window) and restart it
Check that the path in claude_desktop_config.json is correct and uses the right format:
- Mac: /Users/yourname/kirok-mcp (forward slashes)
- Windows: C:\\Users\\YourName\\Desktop\\kirok-mcp (double backslashes)
Check for JSON syntax errors in your config file (missing commas, brackets, etc.)
Look at Claude Desktop logs for error messages

</details>

<details> <summary>"GEMINI_API_KEY not set" or API errors</summary>

Make sure you copied .env.example to .env (not .env.example)
Open .env and verify your API key is there: GEMINI_API_KEY=AIzaSy...
Make sure there are no spaces around the = sign
Make sure the key is valid — test it at Google AI Studio

</details>

<details> <summary>"git: command not found" or "'git' is not recognized"</summary>

Git is not installed on your system:

Mac: Run xcode-select --install in Terminal
Windows: Download from git-scm.com

Alternatively, download Kirok as a ZIP from GitHub (green "Code" button → "Download ZIP").

</details>

<details> <summary>"Connection closed" / server crashes on launch (especially on Windows + cloud-synced folders)</summary>

If the MCP client reports Connection closed or Failed to connect and the server dies before starting, the cause is often the uv run launch command itself, not your code or API key. Verify the environment is healthy first:

# Run with the venv's Python directly so a stuck `uv run` can't get in the way
python -m kirok_mcp.diagnostics --json

If every check passes, the problem is the launcher. uv run re-syncs the project on every launch, which on Windows can fail because:

the running entry-point .exe cannot be regenerated while it is in use (os error 32), or
a cloud-sync service (OneDrive, iCloud Drive, Google Drive) locks files inside .venv, so the sync aborts (os error 5) and can even break the editable install.

Fix: launch the venv's Python directly instead of uv run. This skips sync and entry-point regeneration entirely, and does not depend on the editable install:

{
  "mcpServers": {
    "kirok": {
      "command": "C:\\path\\to\\kirok-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "kirok_mcp.server"],
      "env": { "PYTHONPATH": "C:\\path\\to\\kirok-mcp\\src" }
    }
  }
}

On Mac/Linux use forward slashes and .venv/bin/python. GEMINI_API_KEY is still read from .env, so you do not need to put it in the config. For the Claude Code CLI:

claude mcp remove kirok -s user
claude mcp add kirok -s user -e "PYTHONPATH=/path/to/kirok-mcp/src" \
  -- /path/to/kirok-mcp/.venv/bin/python -m kirok_mcp.server

After changing the config, reconnect from the /mcp menu — a full client restart is usually not required.

</details>

📂 Project Structure

kirok-mcp/
├── src/kirok_mcp/
│   ├── __init__.py       # Package metadata
│   ├── server.py         # MCP server + 19 tool definitions
│   ├── db/               # SQLite database layer, split by domain
│   │   ├── core.py       #   MemoryDB facade (composes the mixins below)
│   │   ├── schema.py     #   Tables, FTS5 + sqlite-vec setup & migrations
│   │   ├── memories.py   #   Memory CRUD
│   │   ├── search.py     #   FTS5 keyword search + vector KNN
│   │   ├── observations.py #  Observation CRUD
│   │   ├── models.py     #   Mental model CRUD
│   │   ├── banks.py      #   Bank stats/config/deletion + failure log
│   │   └── base.py       #   Shared helpers (vectors, paths, sanitizing)
│   ├── backup.py         # kirok-backup CLI (export/import/snapshot)
│   ├── diagnostics.py    # kirok-doctor offline checks
│   ├── retry.py          # Bounded exponential backoff for API calls
│   ├── llm.py            # Gemini LLM for extraction & reflection
│   └── embeddings.py     # Gemini Embeddings + similarity utils
├── docs/
│   ├── architecture.md   # Detailed system design
│   └── tools-reference.md # Complete tool documentation
├── .env.example          # Environment template
├── pyproject.toml        # Project metadata & dependencies
├── LICENSE               # MIT License
├── CHANGELOG.md          # Version history
└── CONTRIBUTING.md       # Contribution guidelines

📜 License

MIT License — see LICENSE for details.

🙏 Acknowledgements

Model Context Protocol (MCP) by Anthropic
Google Gemini API for embeddings and LLM
Mem0 for inspiration on smart deduplication
Reciprocal Rank Fusion (Cormack et al., 2009)

Kirok

README

📝 Kirok

✨ What Can Kirok Do?

🎁 Bonus: Core "Kirok" Agent Skill Included

🚀 Getting Started (Step by Step)

Step 1: Install Python 3.12+

Step 2: Install uv (Python Package Manager)

Step 3: Get a Gemini API Key (Free)

Step 4: Download and Install Kirok

Step 5: Configure Your API Key

Step 6: Connect to Claude Desktop

Find the config file

Add Kirok to the config

Restart Claude Desktop

Step 7: Verify It Works

🔧 Other MCP Clients

🏗️ Architecture

📖 Tools Reference

Core Operations

Memory Management

Mental Models

Bank Management

Configuration

⚙️ Configuration

🩺 Diagnostics

💾 Backup & Restore

🧪 How It Works

The Retain → Recall → Reflect Loop

Memory Banks

🧑‍💻 Development

❓ Troubleshooting

📂 Project Structure

📜 License

🙏 Acknowledgements

推荐服务器