Provides persistent memory tools for GitHub Copilot, enabling automatic fact extraction from session transcripts, semantic recall, and shared memory across the team.
Click on "Install 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., "@bikky recall our team's coding conventions"
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.
bikky provides long-term memory for MCP-capable AI coding agents. It exposes memory tools over the Model Context Protocol (MCP), stores facts in Qdrant, and can run a local daemon that extracts durable facts from supported transcript sources. Teams can share memory across tools, repos, and engineers without treating chat history or closed PRs as the source of truth.
👥 Teams & software factories — What one engineer's agent learns today can be recalled by other agents on the team tomorrow. Shared memory makes institutional knowledge queryable, helps onboarding, and reduces convention drift and repeated rediscovery.
🤖 Multi-agent engineering workflows — Multiple MCP-capable agent sessions can share codebase context, conventions, and recent decisions instead of re-learning them from scratch.
bikky gives your agent memory tools and runs a small background service after bikky setup. You keep working normally; bikky captures useful facts from supported transcript sources, organizes them, recalls them in future sessions, and keeps the store tidy over time.
Capture — Facts are extracted automatically from supported session transcripts without requiring manual notes for every fact.
Classify — Memories are grouped as engineering, product, or system so they stay easy to browse and filter.
Recall — New sessions can recall from the same store via semantic search.
Curate — bikky merges duplicates, fades stale facts, resolves contradictions, distills recurring patterns, and builds an entity graph over time.
Compound — Later sessions can start with more context because memory accumulates.
Route — Optionally keep team, client, or environment-specific memory in separate Qdrant destinations from one install. See routing and ignore rules.
Protect — Configurable ignore rules prevent matching topics from being stored at all, using the same filters as destination routing.
Subtypes keep recall precise without making setup harder:
Engineering — codebase maps, architecture decisions, infra topology, access patterns, operational procedures, troubleshooting gotchas, conventions, preferences, person/ownership context, working agreements, and durable activity events.
Product — domain rules, product decisions, requirements, user workflows, roadmap items, success metrics, and market insights.
System — session indexes, episodes, workstreams, and feedback signals.
bikky has two integration surfaces: MCP tool access for agents and optional background transcript capture. Tool access is broader than transcript capture.
Client or agent | MCP tool access |
| Background transcript capture |
GitHub Copilot | Supported | Supported via | Supported from |
Claude Code | Supported | Supported via the | Supported from |
Cursor and other stdio MCP clients | Standard MCP server is available via | Not auto-configured today | No built-in watcher today |
If your client can launch a stdio MCP server, it can use bikky's memory tools after manual configuration. bikky does not currently ship Cursor-specific setup or transcript parsing. Automatic transcript ingestion is implemented for GitHub Copilot and Claude Code.
Component | Supported today | Notes |
Vector store | Qdrant | Local Docker, Qdrant Cloud, or self-hosted Qdrant. Qdrant is required. |
|
| Used to embed memories for semantic search. |
|
| Used for extraction, curation, distillation, and relation inference. |
Portkey support means bikky talks to Portkey as the configured gateway; upstream model availability, routing, and fallbacks are controlled by your Portkey configuration. Providers not listed above are not built in today, but the provider registry is designed to make additions small and reviewable.
Related MCP server: arcane
This is the fastest path to a working memory store: Qdrant runs locally, while hosted embeddings and LLM calls handle extraction and recall without running local models.
# 1. Pull and run Qdrant (vector store)
docker run -d --name qdrant -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
# 2. Install bikky
npm install -g bikky
mkdir -p ~/.bikky
# Replace sk-... below with your hosted model API key.
cat > ~/.bikky/config.json <<'JSON'
{
"qdrant_url": "http://localhost:6333",
"qdrant_api_key": "",
"embedding": {
"provider": "openai",
"model": "text-embedding-3-small",
"dimensions": 1024,
"api_key": "sk-..."
},
"llm": {
"provider": "openai",
"model": "gpt-4.1-mini",
"api_key": "sk-..."
}
}
JSON
# qdrant_api_key is optional; leave it empty or omit it for local Qdrant.
# Prefer env vars? Omit api_key above and set OPENAI_API_KEY instead.
# 3. Register bikky with supported clients and start the background service
bikky setup # writes MCP config for GitHub Copilot + Claude Code, then starts the daemonnpm install -g bikky runs a best-effort postinstall setup hook for convenience. It never fails the install, and you should still run bikky setup after writing your config to make setup explicit and repeatable.
If setup finds running bikky mcp servers from older agent/editor sessions, it prints reload guidance but does not terminate them:
GitHub Copilot CLI: run /restart in the Copilot CLI session.
Claude Code: restart Claude Code, then run claude --continue or claude -c to resume.
Other stdio MCP clients: use their MCP reload/restart action if available; otherwise restart the client session.
The memory tools appear automatically in GitHub Copilot and Claude Code; configure other stdio MCP clients manually with npx -y bikky mcp.
bikky status # confirms Qdrant, embeddings, daemon, and UI healthAt this point, you can continue with local Qdrant or move the vector store to Qdrant Cloud later for a shared team setup.
For other deployment shapes — fully hosted, 100% local, or hosted Qdrant with local models — see Setup options.
bikky supports four common setup shapes. Pick based on where you want Qdrant to run and where model calls should happen.
Component | Required | Options |
Node.js | ≥ 20 |
|
Vector store | Qdrant | Local Docker · Qdrant Cloud · Self-hosted |
Embeddings | One provider | Portkey · OpenAI · Ollama · Bedrock |
LLM | One provider | Portkey · OpenAI · Ollama · Bedrock |
Docker (optional) | Only if you run Qdrant locally | Docker Desktop, OrbStack, colima, etc. |
Both embedding.provider and llm.provider accept the same values: ollama, openai, bedrock, or portkey. Portkey can be used as a hosted gateway when you want one configured provider in bikky and upstream routing/fallbacks managed outside bikky. The documented examples use 1024-dimensional embeddings because that size works across the built-in provider examples. Some providers expose larger native dimensions (for example OpenAI text-embedding-3-small can return 1536), but using 1024 keeps the documented setup portable without rebuilding every collection.
⚠️ Qdrant Cloud free tier does not include automatic backups. Deleted collections cannot be recovered. If your memory data is valuable, use a paid Qdrant Cloud plan (which includes daily backups), run Qdrant locally with your own backup strategy, or periodically export snapshots via the Qdrant snapshots API.
Setup | Use when | Config |
Fully hosted | Teams want managed vector storage and hosted models | |
Local Qdrant + hosted models | You want local vector storage with hosted extraction/embedding | |
Local and free | You are evaluating locally and can accept local-model quality | |
Hosted Qdrant + local Ollama | You want shared vectors while keeping model calls local |
Pick the setup guide above for the copy-paste config. All setup shapes use the same three building blocks:
Qdrant — where vectors and memory payloads are stored.
Embeddings — how facts become searchable vectors.
LLM — how session transcripts are extracted, curated, and distilled.
Config lives at ~/.bikky/config.json, or at BIKKY_HOME/config.json when BIKKY_HOME is set. You can keep credentials out of the file with environment variables such as QDRANT_URL, QDRANT_API_KEY, and provider API keys.
bikky setup also provisions identity.user_id / identity.user_name when they are missing. New memory writes store canonical origin metadata with the configured human user, the acting agent or daemon/UI surface, the interface, and the operation. MCP clients cannot supply or spoof origin.user; if config, env, Git, and shell identity detection all fail, bikky falls back to the local hostname.
For hosted models, custom providers, multiple destinations, ignore rules, or advanced tuning, use the full configuration guide.
📖 Full configuration guide: docs/configuration.md
🔒 Privacy-first setup: local storage, local models, and transcript-capture controls
🛠 Want to add a new embedding or LLM provider (Vertex, OpenRouter, etc.)? See CONTRIBUTING.md — it's a single-file change.
Most installs use one Qdrant destination. If you need clean separation later, replace the single qdrant_url / collection fields with named destinations[]. Add top-level ignore[] rules for topics that should not be stored anywhere:
{
"destinations": [
{
"name": "platform",
"description": "Shared platform engineering memory.",
"qdrant_url": "https://platform.cloud.qdrant.io:6333",
"qdrant_api_key": "...",
"collection": "bikky-platform",
"default": true
},
{
"name": "client-a",
"description": "Client A project memory.",
"qdrant_url": "https://client-a.cloud.qdrant.io:6333",
"qdrant_api_key": "...",
"collection": "bikky-client-a",
"match": {
"cwd": ["^/Users/me/code/client-a"],
"content": ["CLIENTA-\\d+"]
}
}
],
"default_search_scope": "routed",
"ignore": [
{
"name": "do-not-store",
"description": "Never persist memories explicitly marked do-not-store.",
"match": {
"entity": ["^do-not-store$"],
"content": ["\\bdo-not-store\\b"]
}
}
]
}That is enough for explicit selection in the UI and tools. Add routing rules only when you want automatic placement by cwd, entity, content, or metadata. Search tools can also use search_scope: "all" or a named/listed scope when context may span stores. Ignore rules run before destination selection and cannot be bypassed by explicit destination overrides. Existing single-Qdrant configs continue to work.
📖 Details: multi-destination configuration and ignore rules
bikky-ui is a local dashboard for browsing and managing your team's memory — facts, entities, quality metrics, aggregate impact insights, and the relationship graph.
npx bikky-ui # one-shot — no install needed
# or install globally
npm install -g bikky-ui
bikky-ui # opens http://localhost:1422The UI reads from your existing ~/.bikky/config.json (or BIKKY_HOME/config.json) — no extra configuration required.
By default, the dashboard, memory list, and search results show current user-facing memories only. Internal telemetry, system lifecycle summaries (session_index, episode, workstream), entity sidecars, and superseded archive records are hidden from the main views so counts match what you normally mean by "memories." Diagnostic API queries can still request those records explicitly, including superseded records with include_superseded=true.
Memory cards and detail pages also surface provenance from canonical origin metadata: the configured user, origin surface/operation, agent, last operation, repo, branch, workstream, task, session, and episode when present. Older records that only have legacy source, actor_id, or metadata.actor_label still display useful fallback labels.
bikky mcp # start MCP server (stdio) — used by editors
bikky setup # install MCP configs for GitHub Copilot + Claude Code, then start the daemon
bikky start # alias for setup
bikky stop # stop the background daemon
bikky daemon # run the daemon in the foreground
bikky status # check memory system health
bikky ui # launch the local web dashboard
bikky render # render a prompt to JSON (for eval harnesses & debugging)bikky status is the first thing to run when setup feels wrong. It checks the config, Qdrant, embeddings, background daemon, and local UI health, then tells you what needs attention. Use bikky status --json for automation.
bikky stores memory in the Qdrant destination you configure. The daemon runs locally and reads supported coding-agent transcript locations so it can extract durable facts for future sessions:
GitHub Copilot session state: ~/.copilot/session-state
Claude Code project transcripts: ~/.claude/projects
Only the configured daemon process reads these files. Extracted facts are redacted before storage, but they are still sent to your configured LLM provider for extraction unless you use a local provider such as Ollama. To disable transcript capture, set the relevant watcher to false in ~/.bikky/config.json:
{
"watchers": {
"copilot": { "enabled": false },
"claude": { "enabled": false }
}
}You can also set daemon.extract_every_sec to 0 to disable background extraction while keeping MCP recall tools available.
If you want to prevent memory writes for a single session without changing global config, use the memory_pause MCP tool:
memory_pause({ reason: "private session", session_id: "<your-session-UUID>" })While paused:
All MCP write tools (memory_store, memory_session_summary, memory_distill, memory_verify, memory_forget, etc.) return a session_paused status instead of executing.
Read tools (memory_recall, memory_entity, memory_relations, memory_heartbeat) continue to work normally.
When session_id is provided, the daemon also skips transcript extraction for that session.
Call memory_resume({ session_id: "<your-session-UUID>" }) to re-enable writes.
The session_id is the UUID from your session folder (e.g. the directory name under ~/.copilot/session-state/). If omitted, only the in-process MCP layer is paused — the daemon will continue extracting from transcripts.
For a local-storage, local-model setup that minimizes what leaves your machine, see the privacy-first quickstart.
For questions, bugs, and feature requests, please use GitHub issues. For maintainer contact, reach Saber Zrelli on GitHub: @zrelli-s.
AGPL-3.0 — see LICENSE.
Persist Qdrant and embedding credentials to ~/.bikky/config.json and bring the memory system online. Call this only during onboarding (or when rotating credentials). After it succeeds, the collection is created if missing and embeddings are tested. For day-to-day use, prefer get_setup_status.
| Name | Required | Description | Default |
|---|---|---|---|
| qdrant_url | No | Qdrant REST URL — Qdrant Cloud (https://xxx.cloud.qdrant.io:6333), local Docker (http://localhost:6333), or self-hosted | |
| openai_api_key | No | OpenAI API key (for OpenAI embedding/LLM provider) | |
| qdrant_api_key | No | Qdrant API key — required for Qdrant Cloud; optional / leave blank for unauthenticated local or self-hosted instances |
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 discloses that it persists credentials to a specific file, brings the memory system online, creates a collection if missing, and tests embeddings. However, it does not specify idempotency, error behavior, or what happens on invalid credentials. This is a useful but not exhaustive disclosure.
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?
Three tightly focused sentences: first states the core action, second provides when-to-use, third gives alternative. No wasted words, efficient 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 no output schema and no annotations, the description covers the main behavior, side effects, and usage context. It lacks details on failure modes or verification of success, but it is reasonably complete for a setup tool. It compensates for the missing annotations by providing key behavioral context.
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 100% and each parameter already has a clear description. The description adds no additional meaning beyond what is in the schema, so the baseline of 3 applies.
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 'Persist' and the resource 'Qdrant and embedding credentials', and specifies the side effects of bringing memory system online, creating collection, and testing embeddings. It also distinguishes from the sibling tool get_setup_status by noting it is only for onboarding or credential rotation, while day-to-day use should prefer get_setup_status.
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 states when to call: 'only during onboarding (or when rotating credentials)'. Provides an alternative for regular use: 'For day-to-day use, prefer get_setup_status'. This gives clear guidance on usage context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the memory system is configured and reachable. Use this when memory tools return a 'setup_required' error, or once at session start if you're not sure bikky is wired up. Reports which credentials are missing and includes onboarding instructions if anything is incomplete. Read-only — safe to call any time.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It declares 'Read-only — safe to call any time' and describes what it reports (missing credentials, onboarding instructions). No side effects or auth details needed.
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?
Three sentences, each adding value. First sentence states purpose, second gives usage guidance, third details output and safety. No waste.
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?
For a zero-parameter, no-output-schema check tool, the description covers purpose, usage, output, and safety fully. Nothing else needed.
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?
No parameters exist, so schema_description_coverage is 100%. Baseline 3 is appropriate; no additional param info needed.
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 'Check' and resource 'memory system configured and reachable'. It distinguishes itself from siblings like memory_verify and memory_heartbeat by focusing on setup status and credential reporting.
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?
Explicit usage conditions are given: when memory tools return a 'setup_required' error or at session start. No exclusions or alternatives are mentioned, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a distilled convention — a reusable learning, pattern, or runbook synthesized from multiple prior memories. Stored as kind='distilled', memory_subtype='convention' with canonical origin metadata. Use this when you've noticed a pattern across several prior facts/sessions that's worth surfacing as its own atomic learning. The new memory will rank above raw facts in semantic recall because distilled patterns are higher-signal. Provide 'supersedes' if this distillation replaces an earlier convention. The original stays in storage but is excluded from recall.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository or project surface this learning applies to. | |
| content | Yes | One-sentence reusable convention or pattern. Should be self-contained and applicable beyond a single situation. | |
| entities | Yes | Lowercase entity names this distillation applies to (services, tools, concepts). | |
| task_key | No | Task or issue key associated with this learning, if relevant. | |
| supersedes | No | ID of an earlier distilled fact that this one replaces. Old fact is marked superseded and excluded from recall. | |
| destination | No | Optional destination override. Omit to let routing rules decide. | |
| workspace_id | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses ranking above raw facts, supersedes mechanism (old stays but excluded), and destination override. Could mention idempotency or return values.
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?
Mostly concise and front-loaded with purpose. Each sentence adds value. Slightly lengthy but structured well.
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 7 params and no output schema, description explains subtype, recall behavior, supersedes, destination, and even notes workspace_id is no-op. Comprehensive for its complexity.
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 100% but description adds value beyond: explains supersedes effect and destination override purpose. Provides context for entities and content formatting.
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 'Persist' and resource 'distilled convention' with specific attributes (kind='distilled', memory_subtype='convention'). It distinguishes from raw facts by emphasizing higher-signal recall.
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 tells when to use: pattern across facts/sessions. Contrasts with raw facts. Could add explicit 'when not to use' but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get everything bikky knows about a specific entity — facts mentioning it plus typed relations into and out of it. Prefer this over memory_recall when the user asks 'tell me about X' or 'what do we know about X' and X is a known entity name (service, person, repo, concept). Faster and more complete than semantic search for entity-centric queries. If you only have a fuzzy description, use memory_recall first to find the entity name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Entity name (case-insensitive, e.g. 'qdrant', 'workspace_id'). Should match the lowercase canonical form used when facts were stored. | |
| limit | No | Max facts to return (default 20). Relations are always returned in full, capped at 50 each direction. | |
| destination | No | Optional legacy single-destination override. Do not combine with search_scope. | |
| search_scope | No | Optional read/search scope. Accepts 'routed', 'all', a destination name, a configured scope name, a comma-separated destination list, or an array of destination names. Omit to use config.default_search_scope. | |
| workspace_id | No | [Removed in v0.4.0] No-op. | |
| include_legacy_workspace | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses that relations are always returned, capped at 50 each direction, and that name matching is case-insensitive. This adds useful context beyond the schema, though it does not explicitly state read-only nature or performance characteristics.
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?
Three sentences, front-loaded with primary purpose, then usage guidelines. Every sentence adds value with no fluff.
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 output schema and 6 parameters, the description adequately covers what the tool returns (facts and typed relations), usage guidelines, and parameter behavior. It could mention the return structure but is sufficient for entity lookup.
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 100%, baseline is 3. The description adds value by explaining the name parameter is case-insensitive with an example, and clarifies that destination is a legacy override not to combine with search_scope. These additions justify a 4.
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 retrieves all known facts and relations about an entity, and explicitly distinguishes it from memory_recall by specifying entity-centric queries. It names the alternative and gives preference rules.
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 explicit when-to-use: 'Prefer this over memory_recall when the user asks tell me about X or what do we know about X and X is a known entity name.' Also provides when not to use: 'If you only have a fuzzy description, use memory_recall first.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a fact as superseded/wrong. The fact stays in storage (for audit) but is excluded from all recall results. Use this when a fact was simply incorrect or no longer applies and there is no replacement. If you have a corrected version, use memory_store with 'supersedes: ' instead — that way the new fact stays linked to the old one.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | Short human-readable reason this fact is being retired (stored in 'superseded_by' for future audit). | |
| fact_id | Yes | ID of the fact to forget (returned by memory_store / memory_recall as 'id'). | |
| workspace_id | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that fact stays in storage for audit but excluded from recall results, providing full behavioral context beyond annotations (none provided).
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 concise sentences, front-loaded with purpose, no redundant 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?
No output schema, but description fully explains what happens (audit retention, exclusion from recall) and parameters are well-documented in schema.
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 100%, so baseline is 3. Description does not add extra detail beyond schema's parameter 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?
Clearly states the tool marks a fact as superseded/wrong, distinguishes it from memory_store by explaining the difference when a corrected version exists.
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 tells when to use (fact incorrect/no replacement) and when not to (if corrected version exists, use memory_store with supersedes), with clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reflection check-in. Returns up to three things: a memory nudge if you haven't stored anything in 10+ minutes, stale-fact alerts every 3rd call (with IDs you can pass to memory_verify or memory_forget), and a reflection prompt asking whether the last few minutes of work produced anything worth storing. Call periodically during interactive sessions — roughly every 10 minutes or every 3rd user prompt. No arguments. Cheap and read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavioral traits: it explains the conditions for each return type (e.g., memory nudge if no storage in 10+ minutes, stale-fact alerts every 3rd call, reflection prompt always). It also states 'Cheap and read-only' and 'No arguments.' No contradictions.
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?
Three concise sentences with no wasted words. The first sentence states the purpose, the second details the returns, and the third gives usage frequency. Well-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?
For a tool with no parameters and no output schema, the description is remarkably complete. It explains all three return types, their triggering conditions, and usage frequency. Fully addresses the tool's complexity.
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 zero parameters, the baseline is 4. The description adds context about what the tool returns and under what conditions, which is meaningful beyond the empty 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 identifies 'memory_heartbeat' as a 'Reflection check-in' that returns up to three distinct items: memory nudge, stale-fact alerts, and a reflection prompt. It uses specific verbs and resources, differentiating it from sibling tools like memory_verify and memory_forget.
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 explicit guidance: 'Call periodically during interactive sessions — roughly every 10 minutes or every 3rd user prompt.' Also notes 'No arguments. Cheap and read-only,' which helps the agent decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report that a previously recalled fact actually helped you answer the user's question or complete a task. Bumps a 'useful_count' counter on the fact and writes a telemetry feedback_event row that future ranking work can aggregate. Call this AFTER you used a fact from memory_recall / memory_entity and confirmed it was helpful — not for every recalled fact. If the fact was wrong or misleading, use memory_report_outcome with outcome='wrong' or 'misleading' instead.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional short note about how the fact was useful (e.g. 'unblocked auth debug'). Stored on the telemetry event for future analysis. | |
| fact_id | Yes | ID of the fact that was useful (from memory_recall or memory_entity). | |
| workspace_id | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses side effects: bumps 'useful_count' counter, writes telemetry feedback event, and notes workspace_id is a no-op. This meets the burden for transparency.
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?
Single concise paragraph, front-loaded with purpose, no wasted words. Every sentence adds essential context.
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 output schema, description sufficiently covers purpose, timing, alternatives, and side effects. An agent can correctly decide when and how to invoke this 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 100%, baseline 3. Description adds value by clarifying fact_id source (memory_recall/memory_entity), note purpose (telemetry), and workspace_id deprecation. Extra context justifies a 4.
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 reports a helpful recalled fact, with specific verb 'Report' and resource 'fact'. It explicitly distinguishes from sibling 'memory_report_outcome' by stating alternative for wrong/misleading facts.
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 guidelines are explicit: call only after confirming fact was helpful, not for every recalled fact. It provides a clear alternative: use memory_report_outcome for wrong/misleading facts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause all memory writes for the current session. While paused, memory_store, memory_session_summary, memory_distill, memory_verify, memory_forget, memory_mark_useful, memory_report_outcome, and memory_review (write actions) will return a session_paused status instead of executing. Read operations (memory_recall, memory_entity, memory_relations, memory_heartbeat) remain fully functional. Use when the user says something like 'do not remember anything from this session' or 'pause memory'. Call memory_resume to re-enable writes.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional reason for pausing (e.g. 'user requested private session'). Included in the paused status response. | |
| session_id | No | The session UUID (e.g. from the session folder path). When provided, also signals the daemon to skip extraction for this session. For Copilot sessions, pass the UUID from ~/.copilot/session-state/<UUID>/. Format: just the UUID, the 'uuid:' prefix is added automatically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully explains behavior: write actions return session_paused status, read operations remain functional. Lists affected tools.
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?
Efficient front-loading with main effect first, then structured list of affected tools, usage examples, and resume instruction. No redundant sentences.
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 all necessary aspects: what happens to writes, reads unaffected, how to resume, and optional parameters. No output schema needed for this 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 100%, baseline 3. Description adds context on session_id's dual purpose (skip extraction) and reason being included in response.
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 'Pause all memory writes for the current session.' Lists exactly which write tools are affected, distinguishing it from memory_resume and other 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?
Explicit usage examples: 'Use when the user says something like do not remember anything from this session or pause memory.' Also directs to call memory_resume to re-enable writes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic + filtered search over memory. Returns facts ranked by relevance (vector similarity blended with recency, importance, and reinforcement). Three main uses:
Session-start briefing — broad query like 'session briefing: user preferences, active projects, recent decisions'.
Per-prompt contextual recall — focused query derived from what the user just asked.
Conflict/replacement check — recall similar facts when you suspect new information may supersede an older fact. Deduplication during memory_store is automatic. Combine the natural-language query with structured filters (category, domain, entity, date range, metadata) for tighter results. If you have a known entity name and want everything about it, prefer memory_entity. For 'what does X own/use?' style questions, prefer memory_relations. When multiple Qdrant destinations are configured, use search_scope to choose 'routed' (routing/default behavior), 'all', a destination name, a configured scope name, a comma-separated destination list, or an array of destination names. Call memory_search_scopes to inspect available scopes and descriptions. By default output is human-readable text. Use output_format=json for machine-parseable results with separate results and related arrays. Default limit is 10; maximum effective limit is 50.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by kind: fact, summary, distilled, relation. Optional. Telemetry is excluded by default. | |
| repo | No | Filter by repository or project surface. | |
| limit | No | Max primary results to return (default 10, maximum 50). Values above the maximum are clamped. | |
| query | Yes | Natural-language description of what you're looking for. Embedded and matched semantically — full sentences work better than keyword lists. | |
| since | No | Only facts created on or after this ISO 8601 date or datetime. | |
| until | No | Only facts created on or before this ISO 8601 date or datetime. | |
| branch | No | Filter by branch or working surface. | |
| domain | No | Filter by domain activity profile (same vocabulary as memory_store.domain). Optional. | |
| entity | No | Restrict to facts mentioning this entity (case-insensitive). For full entity context prefer memory_entity. | |
| category | No | Filter by category (same vocabulary as memory_store.category). Optional. | |
| task_key | No | Filter by task or issue key. | |
| episode_id | No | Filter by coherent episode ID. | |
| destination | No | Optional legacy single-destination override. Do not combine with search_scope. Prefer search_scope for routed/all/list search. | |
| graph_depth | No | Entity-graph traversal depth. 0 = vector search only (fast, default). 1 = also surface up to ceil(limit / 2) extra 1-hop entity-related facts (slower; use when the user asks 'what's connected to X?'). In JSON output these are returned separately as related. | |
| search_scope | No | Optional read/search scope. Accepts 'routed', 'all', a destination name, a configured scope name, a comma-separated destination list, or an array of destination names. Omit to use config.default_search_scope. | |
| workspace_id | No | [Removed in v0.4.0] No-op. | |
| output_format | No | Response format. text = backward-compatible human-readable lines (default). json = parseable object with query, limit metadata, results, related, counts, and optional nudge. | text |
| review_status | No | Filter by review lifecycle status (candidate / reviewed / approved / rejected). | |
| memory_subtype | No | Filter by memory subtype (must be valid for the chosen kind). Optional. | |
| origin_user_id | No | Filter to facts whose creation origin.user.id matches this value. Optional. | |
| workstream_key | No | Filter by durable workstream key. | |
| metadata_filter | No | Exact-match filter on the metadata map stored with each fact. All key/value pairs must match (AND logic). | |
| origin_agent_id | No | Filter to facts whose creation origin.agent.id matches this value. Optional. | |
| origin_interface | No | Filter to facts created through this origin interface. Optional. | |
| include_legacy_workspace | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description takes full responsibility for behavioral disclosure. It explains relevance ranking (vector similarity blended with recency, importance, reinforcement), deduplication, output format options, limit clamping, graph_depth behavior, and search_scope mechanics. Slightly missing an explicit read-only declaration, but the nature of 'recall' and the operation parameters imply no mutation.
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-organized with a clear purpose statement, bulleted use cases, and distinct sections for scope and output. It is lengthy but every sentence serves a purpose. Some redundancy exists (e.g., repeated 'optional' notes), but overall efficient for the tool's complexity.
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?
Despite 25 parameters and no output schema, the description covers all essential aspects: usage scenarios, behavioral details, sibling differentiation, parameter hints, output format options, and scope configuration. It provides sufficient information for an AI agent to understand the tool's full capabilities and limitations.
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 100%, setting baseline at 3. The description adds value by elaborating on key parameters: advises using full sentences for query, explains graph_depth's 1-hop behavior, details search_scope flexibility, and clarifies output_format defaults. While some parameters merely restate 'optional', the added context for complex fields boosts the score.
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 identifies the tool as performing semantic + filtered search over memory, with specific verb (recall) and resource (memory). It distinguishes from siblings memory_entity and memory_relations by describing their different use cases (full entity context vs. ownership/use queries), making selection unambiguous.
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 lists three main use cases (session-start briefing, per-prompt recall, conflict/replacement check) and provides clear when-not-to-use guidance by referencing sibling tools. Also directs user to memory_search_scopes for scope configuration, ensuring proper tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query typed edges between entities. Returns 'A --[type]--> B' triples that semantic search alone wouldn't surface. Use for 'what does X own / use / depend on?' and 'who owns Y?' style questions. Optionally filter by direction (from / to / both) and relation type. To create relations, use memory_store with the 'relation' field — there is no separate create-relation tool.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | Entity name to query (case-insensitive). | |
| direction | No | Which side of the edge the entity is on. 'from' = entity is the source (X --[?]--> ?). 'to' = entity is the target (? --[?]--> X). 'both' = either (default). | both |
| destination | No | Optional legacy single-destination override. Do not combine with search_scope. | |
| search_scope | No | Optional read/search scope. Accepts 'routed', 'all', a destination name, a configured scope name, a comma-separated destination list, or an array of destination names. Omit to use config.default_search_scope. | |
| workspace_id | No | [Removed in v0.4.0] No-op. | |
| relation_type | No | Filter to a specific edge label (e.g. 'owns', 'uses', 'decided', 'prefers', 'works-on'). Optional. | |
| include_legacy_workspace | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the behavior: returns triples, optional filters by direction and relation type. It also notes that there's no separate creation tool. However, it does not mention rate limits, authentication needs, or any side effects, but for a read query this is acceptable.
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 with bold for key terms. Every sentence adds value: first states the core function, second gives usage examples and creation alternative. 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?
For a tool with 7 parameters and no output schema, the description provides enough context to use it correctly. It covers the main use case, filters, and how to create relations. Missing details like return format beyond 'triples' or pagination, but it's still complete enough for typical use.
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 100%, so the baseline is 3. The description adds value by explaining the 'destination' parameter as an optional legacy override that should not be combined with search_scope, and by summarizing the filter options. This goes beyond repeating schema definitions.
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 'Query typed edges between entities' and distinguishes itself from semantic search and from the creation tool memory_store. It provides concrete use cases like 'what does X own / use / depend on?', making its purpose unambiguous.
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 explicitly tells when to use this tool ('for 'what does X own / use / depend on?' and 'who owns Y?' style questions') and when not to ('To create relations, use memory_store...'). This leaves no ambiguity about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the downstream outcome of using a recalled fact — useful, misleading, irrelevant, or wrong. Writes a telemetry outcome_event row that future ranking and review work can aggregate. Unlike memory_mark_useful (positive-only, bumps a counter), this records a richer signal including negative outcomes and optional notes. Use this when you can confidently judge whether a fact actually helped: 'useful' = helped you complete the task; 'misleading' = pointed in a wrong direction; 'irrelevant' = matched semantically but didn't help; 'wrong' = factually incorrect (also consider memory_forget for clearly wrong facts).
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Optional short context for the outcome (e.g. 'API moved in v2', 'wrong port number'). Stored on the telemetry event for future analysis. | |
| fact_id | Yes | ID of the fact whose outcome you are reporting. | |
| outcome | Yes | How the fact actually played out. 'useful' = helped you finish the task; 'misleading' = sent you the wrong way; 'irrelevant' = semantically matched but didn't help; 'wrong' = factually incorrect. | |
| workspace_id | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it writes a telemetry outcome_event row for aggregation. With no annotations provided, this covers the core behavioral trait (write side effect) but omits details like authentication 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?
Four sentences that are dense with information: purpose, telemetry side effect, differentiation from sibling, and usage guidelines. 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 4 params, no output schema, and no annotations, the description adequately covers what the tool does and when to use it. Could mention return value or error conditions, but not critical for a telemetry reporting 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 100%. Description adds value by explaining the meaning of each outcome enum and the purpose of notes. It also clarifies workspace_id is a no-op.
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?
Clear verb 'report' and resource 'outcome of a recalled fact'. Distinguishes from sibling 'memory_mark_useful' by noting it handles negative signals and richer data.
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 states when to use this tool vs 'memory_mark_useful', and defines when each outcome value is appropriate (useful, misleading, irrelevant, wrong).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume memory writes after a previous memory_pause. All write operations will function normally again. No-op if memory is not currently paused.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | The session UUID passed to memory_pause. Required to also resume daemon extraction. Same format as memory_pause. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: writes function normally again after resume, and no-op if not paused. No annotations provided, so description carries full burden and does well.
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?
Three short sentences, no fluff. Front-loaded with the main action. Every word adds value.
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?
For a simple tool with one parameter and no output schema, description is complete: it covers state dependency, parameter requirement, and behavior when not applicable.
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 100%, baseline 3. Description adds value by explaining session_id is the UUID from memory_pause and required for daemon extraction, beyond schema's basic description.
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 it resumes memory writes after a pause, with specific verb 'Resume' and resource 'memory writes'. Distinguishes from sibling tool memory_pause.
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 states it is used after memory_pause and notes no-op if not paused, guiding when to use and when not. Does not mention alternatives but context is clear given sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Triage facts that were captured automatically by Bikky (origin.interface='daemon' or legacy source='system'). Only useful when the daemon is running and capturing memories from logs/transcripts; otherwise this returns an empty list. Supports four actions: list (default — show recent daemon/system-captured facts), approve (mark verified), reject (mark superseded with reason), correct (replace with edited content as a new fact).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max facts to return when action=list (default 10). | |
| action | No | What to do. list = show recent system-captured facts (default). approve = confirm a fact is correct (bumps verification count). reject = mark a fact as wrong (requires 'reason'). correct = supersede with an edited version (requires 'corrected_content'). | list |
| reason | No | Required for action=reject. Short reason the fact is wrong. | |
| fact_id | No | Fact ID to act on. Required for approve / reject / correct. | |
| workspace_id | No | [Removed in v0.4.0] No-op. | |
| corrected_content | No | Required for action=correct. The fixed fact text. Stored as a new fact that supersedes the original. | |
| include_legacy_workspace | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes actions and their effects (approve bumps verification, reject marks superseded, correct stores new fact). No annotations provided, so description carries burden; lacks detail on data persistence or undo, but covers core behavior.
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?
Compact single paragraph covering purpose, prerequisite, actions, and key constraints. No wasted words, but could benefit from bullet points for easier 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?
Adequately covers tool purpose, actions, required params, and special cases (daemon dependency, deprecated fields). Missing output description (no output schema), but actions are well-defined.
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 100% and description enhances each parameter with clear context: default limit, action enum values explained, deprecated params noted as no-op, and required fields for actions spelled out.
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 it triages auto-captured facts from daemon/system, lists four specific actions, and distinguishes from sibling tools by targeting daemon/system-captured facts rather than general 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 states when the tool is useful ('only when daemon is running'), warns of empty list otherwise, and describes each action's purpose and prerequisites (e.g., reason for reject, corrected_content for correct).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the configured memory search scopes and destination descriptions. Use this before memory_recall, memory_entity, or memory_relations when multiple destinations exist so you can choose the right search_scope. Read-only — returns built-in scopes ('routed', 'all'), destination-name scopes, configured named scopes, and the default_search_scope.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only' behavior and details the contents returned (built-in scopes, destination-name scopes, configured named scopes, default_search_scope). No annotations present, so description carries full burden; it adds sufficient behavioral context beyond just the name.
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 efficient sentences: first states purpose, second provides usage guidance and output details. No unnecessary 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?
For a simple listing tool with no parameters and no output schema, the description fully explains what it does, when to use it, and what it returns. 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?
No parameters exist, so schema coverage is 100%. Description adds value by explaining what the output contains (list of scopes and descriptions), which aids in understanding results.
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 the configured memory search scopes and destination descriptions' with specific verb 'List' and resource. It distinguishes from siblings by mentioning usage context for memory_recall, memory_entity, etc.
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 instructs to use before memory_recall, memory_entity, or memory_relations when multiple destinations exist, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a compact summary of the current session — what got done, what decisions were made, what's still open. Stored as kind='summary', memory_subtype='session_index' with canonical origin metadata. Keep it short (target 30-80 words). Future sessions retrieve these via memory_recall to bootstrap context faster than re-reading the original transcript. Call this near session close (or at major milestone boundaries) when the work is meaningful enough to want a future agent to inherit. Skip for trivial single-question sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository or project surface this summary relates to. | |
| content | Yes | The summary text. Atomic, self-contained, 30-80 words ideally. Should answer: what was the goal, what did we do, what remains? | |
| entities | No | Lowercase entity names mentioned by the summary (services, repos, people, concepts). Used for entity-scoped recall later. | |
| task_key | No | Task or issue key (e.g. GitHub issue number, JIRA key). | |
| episode_id | No | Coherent activity-segment ID for grouping with related captures. | |
| destination | No | Optional destination override. Omit to let routing rules decide. | |
| workspace_id | No | [Removed in v0.4.0] No-op. | |
| workstream_key | No | Durable continuity key for a long-running objective (survives across sessions). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes storage specifics (kind, memory_subtype, canonical metadata) and future retrieval benefit. However, does not explicitly state write semantics (e.g., does it overwrite?), but 'persist' implies create. No annotations to 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?
Five concise, front-loaded sentences. No redundancy, every sentence adds value. Structure is clear: action, storage details, usage guidance.
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 8 params (1 required), no output schema, no annotations, the description covers purpose, storage details, usage, and future retrieval. Lacks error states or idempotency, but adequate for selection and invocation.
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 100%. The description adds value by explaining content purpose (goal, actions, remaining) and length target (30-80 words). For other params, it mainly echoes schema descriptions but clarifies overall intent.
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 persists a compact session summary with specific content guidance. It distinguishes from siblings like memory_recall (retrieve) and memory_store (generic store) by specifying the kind and subtype.
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 advises to call near session close or milestones, and to skip trivial sessions. Also notes future sessions retrieve via memory_recall, providing clear when-to-use and when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist one atomic fact to long-term memory. Call this whenever you learn something a future session would need: a service detail, a decision rationale, a workaround, a user preference, an ownership fact, a task-resume pointer. One fact per call — split compound observations into separate calls. Dedup is automatic (content hash + vector similarity), so you do NOT need to recall first for deduplication. Recall first only when you intentionally need broader context to decide whether a new fact supersedes an older one. The tool returns one of: inserted (new fact), reinforced (exact or near-duplicate found — counters bumped), or — if there are similar-but-different facts — a list of potential conflicts so you can decide whether to use 'supersedes'. To create a typed edge between two entities at the same time, set the optional 'relation' field — no separate tool call needed. Do NOT use for ephemeral state (current cursor, in-flight todo). Use the harness task folder instead.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Knowledge form of the memory object. One of: • fact — Atomic, durable memory that should be retrievable independently. • summary — Compressed representation of a session index, coherent episode, or current workstream state. • distilled — Convention or reusable learning synthesized from multiple memories. • relation — Typed edge between entities; relation_type carries the edge label. Default when omitted: fact. (telemetry is reserved for the daemon.) | fact |
| repo | No | Repository or project surface this fact relates to (e.g. 'bikky-dev/bikky'). | |
| branch | No | Branch or working surface (e.g. 'main', 'feat/x'). | |
| domain | No | Activity profile that controls vocabulary and ranking. One of: • software_engineering — Coding-agent work: repositories, code changes, architecture, infrastructure, debugging, tests, CI, and developer workflow. • product_strategy — Product direction, positioning, roadmap tradeoffs, customer problems, metrics, and market learning. • business_operations — Business process, vendors, finance, legal/admin operations, recurring procedures, and ownership. • research — Research questions, sources, hypotheses, experiment findings, synthesis, and reusable insights. • personal_productivity — Individual productivity, habits, planning preferences, reminders, and personal operating context. Default when omitted: software_engineering. | software_engineering |
| content | Yes | The fact to store. Should be one atomic, self-contained statement (no compound 'A and B') that makes sense out of context. | |
| category | Yes | Subject matter of the fact. One of: • engineering — Engineering context: codebase maps, architecture decisions, infrastructure topology, access patterns, operations, troubleshooting, and reusable conventions. • product — Product context: domain rules, product decisions, requirements, user workflows, roadmap, success metrics, and market or community insight. • system — System context: Bikky-owned lifecycle memory, session indexes, episodes, workstreams, recall/feedback/outcome telemetry, and aggregate rollups. Default when omitted: engineering. | |
| entities | Yes | Lowercase entity names mentioned by this fact (e.g. ['qdrant', 'workspace_id']). Used for entity-scoped recall and graph traversal — keep them short and canonical. | |
| metadata | No | Arbitrary key-value metadata. Stored with the fact and exact-match filterable via memory_recall.metadata_filter (all key/value pairs must match — AND logic). | |
| relation | No | Optional typed edge between two entities — created in the same call. Use this whenever the fact also expresses a relationship; no separate tool call needed. | |
| task_key | No | Task or issue key (e.g. GitHub issue number, JIRA key). | |
| confidence | No | How certain you are this fact is correct (0.0-1.0). Default 0.9. Lower (~0.6) for inferred or unverified facts. | |
| episode_id | No | Coherent activity-segment ID. Group facts captured during the same coherent task or transcript. | |
| importance | No | How important this fact is for future recall (0.0-1.0). Defaults to 0.5 if omitted. ≥0.8 surfaces in session briefings. | |
| supersedes | No | ID of an existing fact that this one replaces. The old fact is marked superseded and excluded from recall. Use this when a fact is updated; use memory_forget when a fact was simply wrong. | |
| destination | No | Optional destination override. When set, routes to that destination by name. Hard-errors if no such destination exists. Omit to let routing rules in ~/.bikky/config.json decide based on cwd/entities/content/metadata. | |
| workspace_id | No | [Removed in v0.4.0] No-op. Routing now uses destinations — see destination. | |
| review_status | No | Review lifecycle status. candidate=auto-extracted (daemon), reviewed=human-checked, approved=human-confirmed, rejected=incorrect. Agents normally leave this unset. | |
| memory_subtype | No | Optional finer-grained type within the kind. Only set when one of these clearly applies — otherwise leave blank. Subtype must match the kind (validated server-side): • kind=fact: codebase_map, architecture_decision, infra_topology, access_pattern, operational_procedure, domain_rule, product_decision, product_requirement, user_workflow, roadmap_item, success_metric, market_insight, troubleshooting_gotcha, preference, person_profile, ownership_note, working_agreement, activity_event • kind=summary: session_index, episode, workstream • kind=distilled: convention • kind=telemetry: recall_event, feedback_event, outcome_event, aggregate_rollup | |
| workstream_key | No | Durable continuity key for a long-running objective (survives across sessions). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully covers behavioral traits. It explains return values (inserted, reinforced, potential conflicts), dedup mechanism, and the supersedes workflow. It also clarifies that relation edges can be created in the same call.
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 and front-loaded with the purpose. It contains several sentences, but every sentence adds value. Slightly verbose but still clear and organized.
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 tool has 19 parameters (3 required) and no output schema, yet the description covers return types, dedup, relation creation, and exclusions. It provides a comprehensive guide for this complex write 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 100%, so the schema already documents all parameters. The description adds usage context beyond the schema, such as the dedup behavior, one-fact-per-call rule, and how to use the relation field. This adds significant value beyond baseline.
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 'Persist one atomic fact to long-term memory' and distinguishes this tool from siblings like memory_recall and memory_forget. It specifies the verb (persist), resource (memory), and scope (one atomic fact).
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 explicit when-to-use guidance (learning something future sessions need) and when-not-to-use (ephemeral state). It explains dedup behavior and directs users to recall first when broader context is needed. Alternatives like harness task folder are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm an existing fact is still accurate, without re-storing it. Resets the staleness clock and bumps a verification counter. Use this when memory_heartbeat surfaces a stale fact ID and you can confirm it's still true (e.g. you just observed the system in that state). Lighter than memory_store(supersedes:) — same content, fresh timestamp. If the fact is no longer true, use memory_forget or memory_store(supersedes:) instead.
| Name | Required | Description | Default |
|---|---|---|---|
| fact_id | Yes | ID of the fact to verify (from memory_recall or memory_heartbeat). | |
| workspace_id | No | [Removed in v0.4.0] No-op. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: resets staleness clock, bumps verification counter, lighter than memory_store(supersedes:). No annotations provided, so description carries full burden. Adequate coverage for a simple verification 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?
Very concise: 4 sentences, each adding value. Front-loaded with main purpose, then effects, usage context, and alternatives. 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 simplicity of the tool (verify a fact), the description covers the main aspects: purpose, behavior, and when to use. No output schema, but the effects are described. Minor gap: no explicit mention of return value, but acceptable.
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 100%, so baseline 3 applies. The description does not add new information beyond what the schema already provides for the parameters. It repeats the schema's explanation of fact_id and workspace_id.
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 verb ('confirm') and resource ('existing fact'), and distinguishes it from siblings like memory_store(supersedes:) and memory_forget. It specifies that it does not re-store the fact, only verifies accuracy.
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 explicit when-to-use guidance: when memory_heartbeat surfaces a stale fact ID and you can confirm it's still true. Also gives alternatives: if fact is no longer true, use memory_forget or memory_store(supersedes:).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm Qdrant is reachable, embeddings work, and the collection exists. Use this to debug a sudden 'setup_required' or empty-recall after a network blip or credential change. Lighter than configure_credentials — does not write to disk. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses 'does not write to disk' and 'Read-only,' which are key behavioral traits. Could add detail on response behavior, but sufficient for a simple check.
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?
Three concise sentences, front-loaded with purpose. Every sentence adds value with no verbosity.
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?
Tool has no parameters, no output schema, and no annotations. The description covers purpose, usage guidance, and behavioral transparency (read-only, no disk write). Fully adequate for its complexity.
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?
No parameters exist; schema coverage is 100% (trivially). Description adds no parameter info, but baseline 4 applies for zero-parameter tools. No improvement needed.
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 starts with a clear verb+resource: 'Confirm Qdrant is reachable, embeddings work, and the collection exists.' It distinguishes from sibling configure_credentials by noting it is lighter and read-only.
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 states when to use: 'debug a sudden setup_required or empty-recall after a network blip or credential change.' Also contrasts with configure_credentials, providing clear usage context.
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. Dates show when Glama detected each change.
v0.4.6configure_credentialsget_setup_statusmemory_distillmemory_entitymemory_forgetmemory_heartbeatmemory_mark_usefulmemory_pausememory_recallmemory_relationsmemory_report_outcomememory_resumememory_reviewmemory_search_scopesmemory_session_summarymemory_storememory_verifyverify_connectionEach tool has a clearly distinct purpose, ranging from setup and verification to memory storage, recall, maintenance, and pause/resume. Descriptions are detailed and explicitly clarify when to use each tool, preventing confusion.
Core memory tools follow a consistent 'memory_' prefix pattern, but setup tools like 'get_setup_status' and 'configure_credentials' break this pattern. The mix is minor and still readable, but not perfectly uniform.
18 tools is substantial but warranted given the comprehensive coverage of memory lifecycle and maintenance operations. It's slightly on the heavy side but each tool earns its place.
The tool set covers the entire memory lifecycle: setup, storage, retrieval, relation queries, forgetting, verification, feedback, session summaries, distillation, and pause/resume. No obvious gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Shared memory for all your AI agents, your whole team and every MCP client — save, search, recall.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bikky-dev/bikky'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
