--- name: meko-memory description: Use Meko long-term memory and team knowledge from Kiro. Covers session setup without hooks, recall with memory_search and context_search, saving, correcting and clearing memories, datapack routing, knowledge-base search, sharing memories with memory_promote, and error handling for every Meko tool. license: Apache-2.0 metadata: author: Meko version: "1.4.1" tags: mcp, memory, knowledge-base, datapack, meko, kiro --- # Meko memory for Kiro This skill is the detailed reference for the Meko power. The power's instructions cover the session setup; this skill covers how to call each tool correctly the first time and how to read its response. Call every tool through the power with `serverName: "meko"`. Pass only the parameters shown here. When you're unsure about an optional parameter, omit it: the server has defaults. ## Non-negotiable operating contracts Apply these rules before the longer guidance below. They are service-contract safeguards, not suggestions. ### 1. Distinguish failure from an empty search Inspect the response envelope before its contents: 1. If `error` or an error-shaped `detail` is present, or the whole response is an error string (for example `Error searching memories: ...` or `[Errno 111] Connection refused`), the search **failed** and its findings are **unknown**. Say exactly that. Never say "nothing was found," "no results," or "the store is empty." 2. Do not retry quota (`free_tier_limit_reached`), permission (403), or validation errors. Report the error and stop. The one exception is `datapack_access_denied`: retry it once, because the server's access check also fails closed on a transient database error. Retry only documented transient failures (see `tools-troubleshooting.md`), with a bounded backoff. For `PAT_RATE_LIMITED`, wait out the retry-after (about 60s) before retrying. 3. Only a successful response with an explicit empty `results` array proves a legitimate empty search. ### 2. Page through `memory_get_all` before claiming a complete listing `memory_get_all` returns one page of rows (20 by default; `page_size` up to 100) plus `total`, `page`, `page_size`, and `total_pages`. To list everything, repeat the call with `page=2`, `3`, ... up to `total_pages`, keeping every other argument the same. Claim a complete listing only after you have fetched every page and the rows you hold match `total`; rows written while you page can shift later pages. `promoted=true` lists a different set (promoted memories, with its own `total`), not the next page. It takes no `limit` or `offset`. To find one fact, use `memory_search` or `memory_get_by_id` instead of paging. A server older than this paging rejects `page` and `page_size`; there, call it without them and say the result is the newest rows, not a complete listing. ### 3. Separate retrieval breadth from reader context Retrieve up to about 25 candidates for recall, preserve relevance order, and pass at most the top 10 useful evidence items to final reasoning. Never paste all 25–30 results into the reader by default. Raise the reader window only after measuring misses outside the top 10. When dated claims conflict, resolve recency only among claims about the same entity and field; do not sort the whole result set by date. If no candidate supports an answer, abstain: say the retrieved evidence does not cover it. Never fill the slot with a guess, and when the task offers fixed options, choose the one that *means* "not enough information" rather than defaulting to any particular option. ### 4. Verify writes and enforce real isolation - A success-shaped write response is not proof. Read back memories and conversations. For artifacts, compute SHA-256 locally, require the matching `content_hash`, then read back important bytes. A missing hash means the upload is unconfirmed. - A read-back must use the same `datapack_id` as the write. Checking the default datapack after writing to a pinned one proves nothing. - `agent_id` attributes writes; it is not an access boundary. Put projects, tenants, or security domains that must not co-discover content in separate datapacks. ## Session identity on Kiro The power ships no hooks, so nothing injects an `agent_id` or `conversation_id` for you. Set them up once per session, as the power's instructions describe: - `agent_id` is `kiro:` for project facts, `kiro` outside a git repository, and `meko_agent` for facts that apply to every project. An empty `agent_id` on a write lands in `meko_agent`. - `conversation_id` is the `id` that `conversation_create` returns. Create one conversation per session, and never pass a made-up, nil, or `"current"` value. `conversation_create` isn't safe to retry: a retry creates a second conversation. If your context contains `MEKO_CAPTURE_SESSION_STARTED`, the Meko installer's capture hooks are active. Use the IDs they injected and let capture store what the user says. **Read scoping varies by tool:** - `memory_search` and `memory_get_all` return every memory this user owns in the datapack. `agent_id` doesn't filter them, so don't repeat a search per agent. - `memory_delete_all` deletes only the memories stored under the `agent_id` you pass, even though reads span every agent. A `memory_search` preview can show memories this call won't delete. - `conversation_get` only returns conversations created under the same `agent_id`. Any other value returns `agent_id_mismatch`. - `knowledgebase_search` is scoped to the datapack and ignores `agent_id`. ## Datapacks Each datapack has its own memory store and knowledge base. When you omit `datapack_id`, the server uses the user's default datapack. `knowledgebase_search` is the exception: it requires `datapack_id`. - `datapack_search(conversation_id=..., query=...)` finds datapacks by part of the name (`name=` for an exact name) and returns one page: `{datapacks, has_more, next_cursor, total}`. Each row has `datapack_id`, `datapack_name` and the user's `grant` (`owner`, `maintainer`, `contributor`, or `viewer`). For the next page, repeat the call with `cursor=`; it is `""` on the last page. Use it to find a datapack id in an account of any size. - `datapack_list(conversation_id=...)` returns every datapack as one array, which is fine for a small account. Above 1000 datapacks it returns `too_many_datapacks`; use `datapack_search`. On an older server without `datapack_search`, use `datapack_list`. Both tools return `conversation_id_required` when you omit `conversation_id`. - `datapack_describe` returns one datapack's details. - Use one datapack consistently within a session. Put projects that must not see each other's content in separate datapacks: `agent_id` labels writes but doesn't isolate them. Every datapack member can read the knowledge base, so before you add a file, name the file and the datapack, say the team will see it, and wait for the user to agree. Then, if you have the file's bytes and a shell, check that you can reach S3: run `curl -sS -o /dev/null -m 10 -w '%{http_code}' https://s3.amazonaws.com`. A 2xx or 3xx status means yes (S3's root normally answers 307); `000` or any other status means no. If it passes, call `knowledgebase_upload_document` to get a presigned URL, POST the file to it, and check indexing with `knowledgebase_document_status`. With no shell or a failed check, don't call the tool: an unused URL holds storage quota for up to 15 minutes. Accepted types are PDF, TXT, MD, JSON, CSV, XML, and HTML. Otherwise, point the user to the Meko Cloud UI: **Datapack > Actions > Add Knowledge**. ## Recall ### context_search Use it for an open-ended "what do you know about X?" question. It searches the conversation cache, memory, and the knowledge base in parallel and returns each source in its own bucket. ```text context_search(query="deployment conventions for this repo", conversation_id="", agent_id="") ``` ### memory_search Use it when you need personal memories only, or a memory's UUID for `memory_update`, `memory_delete_by_id`, or `memory_promote`. ```text memory_search(query="preferred test framework", agent_id="", conversation_id="") ``` Results below a relevance floor are dropped, so an empty `results` list can mean "no strong match" rather than "nothing stored". ### knowledgebase_search Use it for the team's shared knowledge: uploaded documents and promoted memories. ```text knowledgebase_search(query="incident runbook for the billing service", agent_id="", conversation_id="", datapack_id="", limit=10) ``` ### memory_get_all Follow operating contract 2. It returns one page (20 rows by default) plus `total` and `total_pages`; page through with `page=2..total_pages` for a full listing. ## Save ### memory_add Call it for a durable fact the user states, an explicit "remember this", or a durable fact that appears only in a tool result or your own output. Write one focused fact per call, with the names and identifiers a later search will use. ```text memory_add(text="Deploy scripts must run from the repo root, never a subdirectory", agent_id="", conversation_id="") ``` `text` and `conversation_id` are required. The server extracts facts from the text, so it can shorten or split what you send. ### Correct a stored fact Memory is additive. When the user contradicts a stored fact, find it with `memory_search`, then call `memory_update(memory_id=..., text=..., conversation_id=...)` or `memory_delete_by_id(memory_id=..., conversation_id=...)`. ### Verify after writing Follow operating contract 4. `memory_add` returns `{"results": [{"id": "...", "memory": "..."}]}`. For each returned `id`, call `memory_get_by_id(memory_id="", conversation_id=...)` and confirm the row exists before you tell the user it was saved. If the read-back fails, say the save didn't succeed and include the error. ## Clear memories with memory_delete_all `memory_delete_all` permanently deletes the user's memories in a datapack that one agent stored. Deleted memories can't be recovered, so call it only for a scope the user asked to clear. To remove one memory, use `memory_delete_by_id` instead. - Pass the `agent_id` that stored the memories. Omitting it deletes only the `meko_agent` memories. To clear memories from several agents, call it once per `agent_id`. - Pass `run_id=` to delete only one conversation's memories. A value that isn't a conversation UUID returns `invalid_run_id`. - Omitting `datapack_id` targets the user's default datapack. ```text memory_delete_all(agent_id="", conversation_id="") ``` Read the response before you report the result: - `deleted_count` and `scope` (`datapack_id`, `agent_id`, `user_id`, `run_id`) say what was deleted and where. Report those, not the arguments you sent. - `complete: false` means the call ran out of time with memories left. Call again with the same arguments and add up the counts. - `delete_incomplete` and `delete_failed` mean the call stopped early; `deleted_count` still counts what it removed. See `tools-troubleshooting.md` for what to do next. ## Share memories with memory_promote `memory_promote` moves private memories into the datapack's shared knowledge base and deletes the private copies. There's no rollback. 1. Get exact memory UUIDs from the `id` field of `memory_search` or `memory_get_all` results. 2. Show the user each memory and its UUID. 3. Tell them promotion is one-way, visible to the team, and removes the private records. 4. Call `memory_promote` only after they confirm those exact memories. 5. Only owners and maintainers can promote. On a 403 or any permission error, report it and stop. ## Budget calls `memory_add` takes about 10 seconds for a one-line fact and 20-30 seconds for long text; `memory_search` takes 2-6 seconds. On Free and Standard plans, `memory_search`, `knowledgebase_search`, and `memory_add` draw from lifetime per-user quotas, so avoid redundant calls. ## References | File | What it covers | |------|---------------| | `tools-overview.md` | Tool catalog and a decision tree for choosing a tool | | `tools-cookbook.md` | Per-tool examples with parameters, responses, and error cases | | `tools-memory-vs-conversation.md` | When to use memory tools and when to use conversation tools | | `tools-datapack-workflow.md` | Datapack lifecycle and `datapack_id` routing | | `tools-rag-workflow.md` | End-to-end retrieval flow | | `tools-conversation-reasoning.md` | Recording reasoning with conversation messages | | `tools-troubleshooting.md` | Error recovery and retry rules | | `tools-known-limitations.md` | Lifetime quotas, `memory_get_all` paging, and missing capabilities | | `tools-agent-id-conventions.md` | How `agent_id` attributes writes and how promotion works | | `tools-selflearning-workflow.md` | Read a datapack's weak searches and to-dos, fix them, and verify the fix | | `tools-amp-workflow.md` | Provision an AMP Postgres database, fork branches, and hand over a connection | The references were written for several clients. Where one mentions a SessionStart hook or an injected `agent_id`, use the session identity described above instead.