Kirok is a persistent, searchable memory server for AI agents over MCP, backed by a local SQLite database and Google Gemini AI for embeddings and LLM inference.
Core Memory Operations
Store (KIROK_retain): Save information with automatic entity/keyword extraction, semantic embedding, and smart deduplication (ADD/UPDATE/NOOP decisions).
Smart Store (KIROK_smart_retain): Score content importance (1–10) via LLM before storing — filters low-value content during bulk ingestion.
Search (KIROK_recall): Hybrid semantic + keyword search using Reciprocal Rank Fusion (RRF), with optional time-range filtering and pagination.
Update (KIROK_update_memory): Edit content or context of existing memories, with automatic re-embedding on content change.
Delete (KIROK_forget): Permanently remove a specific memory by ID.
Insight & Reflection
Reflect (KIROK_reflect): Analyze accumulated memories with an LLM to generate higher-level insights saved as "mental models", which can be auto-refreshed.
Consolidate (KIROK_consolidate): Manually trigger synthesis of unconsolidated memories into observations (patterns, preferences, durable knowledge).
Mental Model Management
List, view (KIROK_list_mental_models, KIROK_get_mental_model), refresh (KIROK_refresh_mental_model), or delete (KIROK_delete_mental_model) mental models.
Memory Bank Management
List/Stats (KIROK_list_banks, KIROK_stats): View all banks and detailed per-bank statistics.
Browse/Get (KIROK_list_memories, KIROK_get_memory): Paginate through or fetch specific memories.
Configure (KIROK_set_bank_config, KIROK_get_bank_config): Define a bank's retain and observations missions.
Clear/Delete (KIROK_clear_bank, KIROK_delete_bank): Remove bank contents or entire banks — both require explicit confirm=true with previews as a safeguard.
Reliability & Diagnostics
Atomic writes, soft deletes with audit trails, and startup auto-snapshots ensure data integrity.
Offline CLI for backup, export, and import; kirok-doctor tool checks setup and connectivity.
Provides persistent memory for AI agents using Google Gemini for semantic understanding and search, enabling retention, recall, reflection, and pattern detection across conversations.
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., "@Kirok remember that I prefer dark mode in settings"
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.
English | 日本語
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:
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); 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).
Related MCP server: Memsolus MCP Server
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| geminiStorage 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 checkClaude Code CLI:
claude mcp add kirok -s user -- uvx kirok-mcpClaude 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 setupPoint your MCP client at the checkout with uv run --directory /absolute/path/to/kirok-mcp kirok-mcp instead of uvx kirok-mcp.
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:
{
"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/ 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
Tool | Purpose |
| Store a memory: entity/keyword extraction + embedding + smart ADD/UPDATE/NOOP dedup |
| Hybrid semantic + keyword search (RRF), observations shown first |
| Synthesise memories into a mental model (insight), optionally auto-refreshing |
| Score importance (1–10) first, then retain only if it clears a threshold |
| Manually run observation consolidation for a bank |
Memory management
Tool | Purpose |
| Fetch one memory / browse a bank with pagination |
| Edit content or context (re-extracts and re-embeds on content change) |
| Delete a single memory (irreversible) |
Mental models
Tool | Purpose |
| List / inspect insights from Reflect |
| Re-analyse against current memories |
| Delete a mental model (irreversible) |
Banks
Tool | Purpose |
| List banks with counts / detailed per-bank stats incl. background failures |
| Delete a bank's memories + observations (requires |
| Delete a bank entirely (requires |
Config
Tool | Purpose |
| Set / view a bank's retain & observation "missions" (what to focus on) |
Everything is set via environment variables (typically in .env). Only GEMINI_API_KEY is required.
Variable | Default | Description |
| — | Required. Google Gemini API key. |
|
| SQLite database location. |
|
| Cosine similarity above which retain invokes the LLM dedup (ADD/UPDATE/NOOP) decision. |
|
| Similarity floor for semantic memory hits in recall. Keyword/FTS hits are exempt. |
|
| Similarity floor for observation hits in recall. |
|
| Run auto-consolidation only once this many memories are pending ( |
|
| Consolidation timeout, seconds. |
|
| Reflect timeout, seconds. |
|
| Min hours between startup auto-snapshots ( |
|
| Auto-snapshot generations to keep before rotating out the oldest. |
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 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 10Atomic 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.
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.jsonsnapshot 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 connectivityuv sync
uv run --no-sync pytest # 164 offline tests; no API key or network neededThe 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.
docs/architecture.md — internal design, data model, consolidation engine
docs/tools-reference.md — full parameter reference for all 19 tools
CHANGELOG.md — version history (current: 1.4.2)
MIT — see LICENSE.
Model Context Protocol and the official MCP Python SDK (FastMCP)
Google Gemini API for embeddings and LLM
Mem0 — inspiration for smart deduplication and the knowledge layer
Reciprocal Rank Fusion (Cormack et al., 2009)
Delete ALL memories and observations in a bank, keeping the bank itself. Mental models are preserved. This is destructive and cannot be undone.
Without confirm=true this makes NO changes and returns a preview of what would be deleted. Only pass confirm=true after the user has explicitly approved deleting this specific bank's contents.
Args: bank_id: Bank to clear. confirm: Must be true to actually delete. Defaults to false (preview).
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes | ||
| confirm | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explicitly states this is destructive and cannot be undone, and explains the confirm parameter provides a preview by default.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, well-organized with sections, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers purpose, usage, parameters, and behavioral details with no evident gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains both parameters (bank_id and confirm) with their purposes and default behavior, adding value beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'delete' and resource 'ALL memories and observations in a bank', distinguishing from siblings like KIROK_delete_bank (deletes entire bank) and KIROK_forget (likely deletes individual memories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes preview mode without confirm=true and requires user approval before actual deletion, providing clear when-to-use and safety guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually trigger observation consolidation for a bank.
Processes unconsolidated memories and synthesizes them into observations — patterns, preferences, and durable knowledge.
Args: bank_id: Memory bank to consolidate.
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It explains that memories are synthesized into observations but does not disclose whether unconsolidated memories are deleted, permissions needed, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two clear sentences, though the Args section is slightly informal. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and a single required parameter, the description is adequate but lacks details on what happens to the original memories (e.g., are they deleted?) and the format of output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds a brief explanation for bank_id ('Memory bank to consolidate'), which is an improvement over the schema's bare 'Bank Id' title, but could be more detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it triggers consolidation of unconsolidated memories into observations, distinguishing it from sibling tools like KIROK_forget or KIROK_retain that perform other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Manually trigger' implies intentional use, but there is no explicit guidance on when to use this tool versus alternatives like KIROK_reflect or KIROK_refresh_mental_model.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a bank and ALL its memories, observations, models, and config. This is destructive and cannot be undone.
Without confirm=true this makes NO changes and returns a preview of what would be deleted. Only pass confirm=true after the user has explicitly approved deleting this specific bank.
Args: bank_id: Bank to delete entirely. confirm: Must be true to actually delete. Defaults to false (preview).
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes | ||
| confirm | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes destructive nature, irreversibility, and cascade deletion of all associated data. Documents the preview behavior and the need for explicit user approval. No annotations contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: three short paragraphs and a bullet list of args. No unnecessary words. Front-loaded with the most critical information (destructive, permanent).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the full behavior: what is deleted, safety preview, user approval requirement. The output schema is mentioned as existing, so return value details are assumed covered. Slight gap: could explicitly state preview output format, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no descriptions (0% coverage), but the description fully explains both parameters: bank_id (bank to delete) and confirm (must be true to delete, defaults to false for preview). Adds essential meaning beyond schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently deletes a bank and all associated data (memories, observations, models, config). This differentiates it from siblings like KIROK_clear_bank or KIROK_delete_mental_model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear two-phase usage: preview without confirm=true, actual delete only after user approval. Lacks explicit comparison to alternative tools for deletions but the safety instructions are strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific mental model. This is destructive and cannot be undone.
Args: model_id: ID of the mental model to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the full burden. It mentions destructiveness and irreversibility, which is good, but lacks details on permissions, side effects, or idempotency. Additional context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences plus an argument description, very concise, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and an output schema, the description is minimal. It doesn't mention what the tool returns (e.g., success confirmation) or any prerequisites, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions, but the description adds 'ID of the mental model to delete', providing clear meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete a specific mental model', which is a specific verb and resource. It distinguishes from siblings like get or refresh mental models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that the action is destructive and cannot be undone, implying careful use, but does not explicitly state when to use this tool versus alternatives like refresh_mental_model or list_mental_models.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific memory by its ID. This is destructive and cannot be undone.
Args: memory_id: ID of the memory to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries the burden. It explicitly states 'destructive and cannot be undone,' which clearly conveys the irreversible nature of the operation, though it doesn't detail other potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences followed by a clear parameter documentation. Every sentence adds value, and the destructive warning is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one parameter, no nested objects), and the presence of an output schema (not needing return value description), the description provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an 'Args' section that explains the 'memory_id' parameter, adding meaning beyond the schema's minimal title. Schema coverage is 0% but the description fully compensates for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a specific memory by its ID') with a specific verb and resource, distinguishing it from siblings like KIROK_delete_bank (delete entire bank) and KIROK_clear_bank (clear/remove all).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns the operation is destructive and irreversible, implying careful use, but does not explicitly guide when to use this tool versus alternatives like KIROK_delete_bank or KIROK_clear_bank.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current configuration for a memory bank.
Args: bank_id: Memory bank to query.
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description indicates a read-only operation ('Get'). Lacks details on side effects, authentication, or rate limits, but adequate for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description does not need to detail return values. However, could mention scope of config properties. Still sufficient for a simple getter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (bank_id) with schema coverage 0%. Description adds 'Memory bank to query,' which marginally clarifies the parameter but does not compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get the current configuration for a memory bank,' with a specific verb and resource. Distinguished from siblings like KIROK_set_bank_config and KIROK_list_banks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention exclusions or prerequisites, leaving the agent to infer general usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a specific memory by its ID.
Args: memory_id: The memory ID to look up.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only says 'Get full details', lacking disclosure of behavioral traits such as read-only nature, side effects, or permission requirements. For a read operation, minimal context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise with one sentence plus args list. No unnecessary words, though structure could be improved with bullet points for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return values are covered. However, with only one parameter and minimal behavioral info, the description is adequate but leaves some gaps about when to use and what exactly 'full details' entails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for the single parameter. Description adds only 'The memory ID to look up', which adds little beyond the schema's title. Should provide more context like format or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'full details of a specific memory by its ID'. It distinguishes from siblings like KIROK_list_memories (list summaries) and KIROK_recall (different semantics), though no explicit differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like KIROK_list_memories or KIROK_recall. No prerequisites or when-not-to-use information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a specific mental model.
Args: model_id: The mental model ID to look up.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It implies a read operation ('Get full details') but does not explicitly state it is read-only, idempotent, or free of side effects. Minimal but adequate for a simple retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence and one parameter line. Front-loaded with the action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, output schema exists), the description covers the essential purpose and parameter. Could mention idempotency or error behavior, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains model_id as 'The mental model ID to look up', which provides context beyond the schema's title. However, it lacks format or source guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full details of a specific mental model', identifying the verb and resource. It differentiates from sibling tools like list or delete by focusing on a single model retrieval, but does not explicitly contrast against them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like KIROK_list_mental_models or KIROK_refresh_mental_model. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available memory banks with their memory counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions listing banks with counts, which implies a read-only operation but does not disclose potential traits like pagination or performance. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded and efficiently conveys the tool's action and result.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and the existence of an output schema, the description is sufficiently complete. It covers the essential information for a simple list tool without requiring elaboration on return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100% vacuously. Per guidelines, 0 parameters yields a baseline of 4. The description adds no parameter info beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all available memory banks with their memory counts,' making the purpose unambiguous. It distinguishes from sibling tools like KIROK_delete_bank or KIROK_clear_bank by focusing on listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives (e.g., KIROK_list_memories). Usage is implied for getting an overview of banks, but no exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List memories in a bank with pagination, ordered by most recent.
Args: bank_id: Memory bank to browse. limit: Maximum number of memories to return (default 20, max 100). offset: Number of memories to skip for pagination (default 0).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| bank_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses pagination behavior (limit, offset, defaults, max) and ordering, but does not mention side effects (read-only), performance, error handling, or what happens if bank_id is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise: two-line summary plus parameter list. Front-loads key info. Every sentence contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema existing, description doesn't need to cover return values. It adequately explains input parameters and pagination. Minor gaps: no mention of sort direction or behavior for empty results, but overall complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It does so by noting ordering ('most recent'), limit default and max (20, 100), and offset default (0), which are not in schema. However, it doesn't explain the bank_id parameter beyond its name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List memories in a bank with pagination, ordered by most recent.' It specifies verb (list), resource (memories in a bank), and key details (pagination, ordering). This distinguishes it from siblings like KIROK_get_memory and KIROK_list_banks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (browsing memories in a bank), but no explicit guidance on when to use vs alternatives (e.g., single memory retrieval or other list tools). No when-not-to-use or prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List mental models (insights generated by Reflect) for a bank.
Args: bank_id: Memory bank to list mental models from. limit: Maximum number of models to return (default 10).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| bank_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It implies read-only behavior by describing the action as 'list' and mentions a default limit. However, it does not disclose side effects (none expected), authentication needs, pagination behavior, or ordering. The transparency is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus an Args block. Every word adds value, with the purpose front-loaded ('List mental models') and parameter details compactly listed. No redundancy or filler. It's an model of efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (thus return values are documented elsewhere), the description covers the essential context: what the tool does, its required input (bank_id), and its optional parameter (limit). It does not mention pagination or ordering, which could be relevant for a list operation. Still, for a simple list with output schema, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description provides clear semantics for both parameters: 'Memory bank to list mental models from' for bank_id and 'Maximum number of models to return (default 10)' for limit. This adds meaning beyond the raw schema, which lacks descriptions. The parameter explanations are accurate and helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'list mental models' and specifies they are 'insights generated by Reflect'. It identifies the resource (mental models) and action (list), distinguishing it from siblings like KIROK_get_mental_model (single) and KIROK_refresh_mental_model (update). The resource scope is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is used 'for a bank' and requires a bank_id, providing context for when to use it. However, it does not explicitly state when not to use it or suggest alternatives (e.g., use KIROK_get_mental_model for a specific model). The usage context is clear but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and retrieve relevant memories using semantic similarity and keyword matching, merged with Reciprocal Rank Fusion.
Args: bank_id: Memory bank to search. query: Natural language search query. limit: Maximum number of results (default 10, max 50). time_min: Optional ISO 8601 lower bound for timestamp filtering. time_max: Optional ISO 8601 upper bound for timestamp filtering. verbose: If True, also show relevance scores (RRF/Sim) per item. Default False keeps the output compact (content + ID only) to save context tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| bank_id | Yes | ||
| verbose | No | ||
| time_max | No | ||
| time_min | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the merging algorithm (RRF), the effect of the verbose parameter, and default behavior (compact output). It does not disclose auth needs or rate limits, which is acceptable for a read-only search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then provides a structured parameter list. It is somewhat lengthy but well-organized. A bit more conciseness could be achieved, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description adequately covers input behavior and output format. It mentions default output and verbose option. For a search tool with filters, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has 0% description coverage, the description's docstring provides detailed explanations for all 6 parameters, including default values, formatting hints (ISO 8601), and behavioral notes (verbose saves tokens).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search and retrieve relevant memories using semantic similarity and keyword matching, merged with Reciprocal Rank Fusion.' This is a specific verb and resource, and it naturally distinguishes from siblings like KIROK_list_memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (semantic search with optional filters), but it does not explicitly mention when not to use it or list alternatives. The context helps infer its suitability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reflect on accumulated memories to generate new insights.
Retrieves relevant memories, analyzes them with an LLM, and saves the resulting insight as a 'mental model' for future reference.
Args: bank_id: Memory bank to reflect on. query: What to reflect on (question, topic, or open-ended prompt). limit: Max memories to consider (default 20, max 100). auto_refresh: Whether to refresh this model after future consolidations. source_query: Optional query to use for future refreshes. Defaults to query.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| bank_id | Yes | ||
| auto_refresh | No | ||
| source_query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description clearly explains the process: retrieves memories, analyzes with LLM, saves as mental model. It also details parameters like auto_refresh and source_query for future behavior. No contradictory or missing behavioral traits are apparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first line stating the purpose, a brief process sentence, and a well-organized Args list. No unnecessary words, though it could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's inputs and process adequately. Since an output schema exists but is not provided, it does not need to explain return values. However, it lacks details on error handling or how to retrieve the created mental model, but is largely complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains all 5 parameters, including defaults and max for limit, the purpose of auto_refresh, and the default behavior for source_query. This adds significant meaning beyond the schema's type and default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Reflect on accumulated memories to generate new insights.' It specifies the verb 'Reflect' and the outcome 'generate new insights,' and distinguishes this tool from siblings like KIROK_recall by mentioning it saves insights as 'mental models.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one wants to synthesize memories into insights, but does not explicitly state when to use this tool versus alternatives like KIROK_recall or KIROK_consolidate. No 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh an existing mental model by re-analyzing current memories. Updates the insight based on the latest data in the bank.
Args: model_id: ID of the mental model to refresh. limit: Max memories to consider (default 20, max 100).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states it updates the insight, but does not mention if the operation is destructive, reversible, or requires specific permissions. Since output schema exists, return values are likely covered elsewhere, but side effects are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two clear sentences plus an Args block. Every sentence adds value without redundancy. It is efficiently structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema likely documents return values, the description covers purpose, parameters, and the key behavioral aspect (re-analysis). It does not mention prerequisites (e.g., model must exist) or concurrency, but the tool's simplicity makes it adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explicitly describes both parameters: model_id (ID) and limit (max memories, default 20, max 100), providing constraints and defaults beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'refresh' on a 'mental model', specifying that it re-analyzes current memories and updates the insight. This distinguishes it from sibling tools like get_mental_model (retrieval) and delete_mental_model (deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an existing mental model needs updating with the latest memories, but does not explicitly state when not to use or mention alternatives. Given the sibling context, the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store new information in agent memory.
Automatically extracts entities and keywords, generates a semantic embedding, and indexes for later retrieval.
Smart Deduplication (inspired by Mem0): If the new content is highly similar to existing memories (cosine > 0.85), the system will decide whether to ADD (new info), UPDATE (enrich existing), or NOOP (skip).
Args: bank_id: Memory bank identifier (e.g. 'antigravity', 'user-prefs'). content: The information to remember. context: Optional context about the source (e.g. 'project meeting'). timestamp: Optional ISO 8601 timestamp. Defaults to now.
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes | ||
| content | Yes | ||
| context | No | ||
| timestamp | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses deduplication logic with cosine similarity threshold, the decision to ADD/UPDATE/NOOP, auto-extraction of entities, and indexing. However, it does not mention authorization needs, rate limits, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise summary, followed by detailed behavioral explanations and an Args section. While slightly lengthy, every sentence adds value; minor redundancy (e.g., repeating 'automatically') does not detract significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which covers return values), the description adequately covers input parameters, deduplication behavior, and auto-extraction. It does not mention output format but the schema handles that. Overall complete for a memory storage tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds significant meaning by providing examples (e.g., bank_id: 'antigravity'), clarifying content as 'The information to remember', and specifying defaults (timestamp defaults to now). This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Store new information in agent memory' and details the automatic extraction, embedding, and indexing processes. This effectively distinguishes it from sibling tools like KIROK_forget (removal) and KIROK_recall (retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates use for storing new information, but lacks explicit guidance on when to use this tool versus alternatives such as KIROK_smart_retain or KIROK_update_memory. There is no mention of when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure a memory bank's retain and observations missions.
The retain_mission guides what entities/keywords to extract (and what to ignore). The observations_mission guides what patterns to consolidate into observations.
Args: bank_id: Memory bank to configure. retain_mission: Plain-language description of what this bank should focus on. observations_mission: Plain-language description of what observations to synthesize.
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes | ||
| retain_mission | No | ||
| observations_mission | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether the operation is destructive, whether it overwrites existing config, or if any permissions are required. Only parameter purpose is explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (6 lines) with a clear top-line summary and structured parameter descriptions. Every sentence is useful and there is no redundant or missing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema (so return values need not be described), the description covers the essential purpose and parameters. However, it lacks details on behavioral aspects like overwrite semantics or error handling, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose: bank_id as the target, retain_mission as entities/keywords to extract, and observations_mission as patterns to consolidate. The 'Args' section adds meaningful context beyond parameter titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Configure a memory bank's retain and observations missions') with specific verbs and resources. It distinguishes from sibling tools like KIROK_get_bank_config, KIROK_clear_bank, etc., by focusing on setting configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It simply states what the tool does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate content importance before retaining. Uses LLM to score the content from 1-10 and only retains if score >= threshold.
Use this for bulk/automatic ingestion where you want the system to decide what's worth remembering.
Args: bank_id: Memory bank identifier. content: The information to potentially remember. context: Optional context about the source. timestamp: Optional ISO 8601 timestamp. threshold: Minimum importance score to retain (1-10, default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes | ||
| content | Yes | ||
| context | No | ||
| threshold | No | ||
| timestamp | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the scoring mechanism (LLM, 1-10) and threshold behavior. However, it does not mention cost/rate limits of LLM calls, what happens if the content is below threshold (presumably not retained but not explicitly stated), or any return value structure. Additionally, it does not state that this is a write operation with potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: a one-sentence purpose, a one-sentence usage guideline, then a neatly formatted Args list. Every sentence serves a purpose, with no fluff. It is front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and existence of an output schema (though not shown), the description covers the core logic, usage context, and all arguments. However, it omits details about output/return value, potential prerequisites (e.g., bank existence), and edge cases like invalid timestamps. Still, it provides sufficient guidance for an AI agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description's parameter list adds significant meaning: each param is briefly explained (e.g., 'bank_id: Memory bank identifier', 'content: The information to potentially remember'). Default values are noted. This compensates for the bare schema and provides clear semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: evaluating content importance via LLM scoring and retaining only if above a threshold. It distinguishes this from the sibling 'KIROK_retain' tool, which presumably retains without scoring, making the differentiation explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly guides when to use: 'Use this for bulk/automatic ingestion where you want the system to decide what's worth remembering.' This implies it's for high-volume or unsupervised scenarios, contrasting with simpler retain or other tools. The guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics for a specific memory bank.
Args: bank_id: Memory bank identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| bank_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It merely states 'get statistics,' implying a read operation, but provides no detail on side effects, permissions, or what statistics are included. This is insufficient for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence plus param doc) and front-loaded. Every word serves a purpose, though the args section could be integrated for better structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, output schema present), the description covers the basic purpose. However, with many sibling tools, more detail on what 'statistics' entails would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning to the parameter: 'bank_id: Memory bank identifier.' This is basic but valuable, though it does not explain the format or constraints beyond the schema's type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get statistics for a specific memory bank,' using a specific verb ('get') and resource ('statistics for memory bank'). However, it does not differentiate this tool from siblings like get_memory or list_banks, missing the opportunity to clarify what 'statistics' means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives among 18 sibling tools. The description lacks context for decision-making, leaving the agent to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing memory's content. Re-extracts entities/keywords and regenerates the embedding if content changes.
Args: memory_id: ID of the memory to update. content: New content text (leave empty to keep current). context: New context string (leave empty to keep current).
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | ||
| context | No | ||
| memory_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behaviors beyond a simple update: it re-extracts entities/keywords and regenerates the embedding if content changes. With no annotations provided, the description carries the full burden and adequately addresses the tool's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences of purpose and behavior followed by a bullet-point argument list. Every sentence adds value, and the structure is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, 1 required) and the presence of an output schema, the description covers the essential behavior and argument semantics. It could mention error handling or return value expectations, but the output schema likely fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter's role and default behavior (e.g., 'leave empty to keep current'). It adds meaning beyond the schema titles, though it omits details like expected formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('update'), the resource ('existing memory'), and the primary action ('content'). It also specifies the side effects (re-extraction, regeneration) that differentiate it from read or delete tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying a memory's content but does not explicitly state when to choose this tool over alternatives like KIROK_retain or KIROK_smart_retain. No exclusions or prerequisites are mentioned, though the name and context make the purpose clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.0KIROK_clear_bankKIROK_consolidateKIROK_delete_bankKIROK_delete_mental_modelKIROK_forgetKIROK_get_bank_configKIROK_get_memoryKIROK_get_mental_modelKIROK_list_banksKIROK_list_memoriesKIROK_list_mental_modelsKIROK_recallKIROK_reflectKIROK_refresh_mental_modelKIROK_retainKIROK_set_bank_configKIROK_smart_retainKIROK_statsKIROK_update_memoryScored across 19 tools
Most tools have distinct purposes (e.g., list, get, delete). However, retain and smart_retain are very similar, differing only in an importance threshold. Reflect and refresh_mental_model both deal with mental models but have different actions; still, they could be confused. Overall, the set is mostly clear.
All tools follow a consistent verb_noun pattern with 'KIROK_' prefix and snake_case. No mixing of conventions (e.g., clear_bank, list_banks, get_memory). The naming is predictable and systematic.
With 19 tools, the server covers the full memory management lifecycle (CRUD, search, configuration, consolidation). This is a reasonable scope for a memory bank system, not too many or too few.
The tool set covers most operations for banks, memories, and mental models. However, there is no explicit tool to create a bank (banks seem to be created implicitly or via set_bank_config), and there is no direct way to update a mental model's content (only refresh). These are notable gaps for full lifecycle coverage.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent memory for AI agents. Search, store, and recall across sessions.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Hosted persistent memory with semantic search, importance and TTL for AI agents.
