--- title: "Work with memory" url: "https://docs.mekodata.ai/guides/working-with-memory/" --- # Work with memory Add, search, and list agent memories in Meko through MCP Meko's memory system gives agents persistent recall across sessions. This guide covers memory operations you drive from a coding agent over MCP: add a memory, search for relevant memories, and inspect recently stored memories. Meko can also move memories into shared, institutional knowledge through a separate review flow. That lifecycle, including how candidates are identified and promoted from **Learnings** in the Meko UI, is described in [Learnings](/architecture/core-concepts/learnings/). For information on how extraction and hybrid retrieval work, see [Memory](/architecture/core-concepts/memory/). To choose between a memory, a knowledge-base file, and an artifact, see [Where to store it](/guides/where-to-store/). Memory retrieval Memory search combines semantic similarity, keyword matching, and entity-aware ranking. ## Add memories ### Via MCP (from your coding agent) The simplest way to add memories is through natural language in your coding agent: ```text Please remember that I like to take vacations at tropical beach locations, on a budget ``` ```text Remember this coding preference: I prefer Python type hints and use pytest for testing ``` The MCP server calls `memory_add` behind the scenes and stores the durable fact for later retrieval. ### Automatically, from saved conversations You don't have to explicitly ask your agent to "remember" something for it to become a memory. If your client has automatic capture enabled (the [Automated install](/quick-start/#connect-your-ai-client)) or your agent otherwise saves the turn with `conversation_add_message`, Meko scans the saved turn server-side and creates memories from the durable facts it finds — no extra step required. Extraction is best-effort Conversation-driven extraction runs asynchronously after a turn is saved, and can occasionally miss an individual fact within a longer turn. For anything that must not be lost, explicitly say "remember this" (`memory_add`) rather than relying on automatic extraction alone. ## Search all Meko context For an open-ended question, ask your agent what Meko knows about the subject: ```text What does Meko know about the 2.3 release? ``` The `context_search` tool searches personal memory, shared datapack knowledge, and past conversations in parallel. It returns each source in a separate bucket, so a memory result doesn't hide a newer knowledge-base document. An empty bucket doesn't always prove that the source contains no matching information. Check the source status. If that source failed or wasn't queried, confirm with `memory_search` or `knowledgebase_search` before concluding that nothing is stored. ## Search memories ### Via MCP (from your coding agent) With Meko connected through MCP, your agent can retrieve memories on its own when answering questions that clearly depend on stored preferences or facts. You do not have to name a tool for that to happen. When you want to inspect or force a lookup, for example, to confirm what was saved, ask in natural language, as in the following examples. Example 1: ```text What are my vacation preferences? ``` Example 2: ```text What coding standards have I set? ``` The MCP server performs a hybrid search across your memories and returns the most relevant results. `memory_search` spans the current user's agent namespaces in the selected datapack. For example, a search from Claude Code can find a relevant memory written from Cursor or Claude Desktop. The `agent_id` sent with the search is used for trace attribution; it doesn't filter the results. Agents should make one search rather than repeating it for every known agent ID. Retrieval size and LLM context Retrieving all memories or running a broad memory search can add substantial content to your LLM context. Set `memory_search.limit` to return fewer search results when appropriate. See the [MCP memory tools reference](/reference/mcp-server/#memory-tools) for details. ### How search works Memory search combines three signals: 1. **Semantic similarity** finds memories with related meaning. 2. **Keyword matching** gives exact terms more weight. 3. **Entity boosting** raises memories that mention the named people, projects, or tools in the query. Meko combines these signals into `score` and orders results by that field. `raw_similarity_score` is the vector store's cosine similarity and does not determine the order by itself. For example, the memory *"John likes bananas"* can match the exact query *"Who likes bananas?"* and the related query *"Who likes fruit?"* ## View recent memories To inspect your recent memories in a datapack, ask your coding agent in plain language. For example: ```text Show my recent Meko memories in the default datapack. ``` `memory_get_all` returns roughly 20 recent rows and a `total` count across your agent namespaces. It isn't a complete list, and MCP doesn't currently provide a complete memory export. Use `memory_search` to find older memories or `memory_get_by_id` when you know an exact ID. Don't call `memory_get_all` repeatedly or add pagination arguments. The tool returns the same recent window and rejects unsupported pagination fields. ## Delete a memory On the datapack, select **Memories** to show the **Memory Summary**. Click **Delete** and confirm to permanently remove your memory from the datapack. On **Collective Memory**, an owner or a maintainer can delete a promoted memory. Click **Delete** and confirm. Search no longer returns that memory. A member whose role changed to **Viewer** can still delete their own memories from **Memories**. Limitation Memory deletion is only available for memories created *on or after September 9, 2026*. Older memories can't be deleted. This includes collective memory. ## Promote memories to shared knowledge Datapack owners and maintainers can use `memory_promote` to move private memories into the datapack's shared knowledge base and Collective Memory. Promotion removes the selected records from private memory and can't be reversed through the MCP tool. `memory_search` still returns memories you promoted, along with your private memories. Before promoting, your agent should: 1. Retrieve and show the exact memories it will promote. 2. Explain that datapack members will be able to find the promoted knowledge and that the private records will be removed. 3. Ask for explicit confirmation. 4. Call `memory_promote` only after you confirm. For the complete shared-knowledge lifecycle, see [Learnings](/architecture/core-concepts/learnings/). ## Next steps - [Learn about memory](/architecture/core-concepts/memory/) - [Learnings](/architecture/core-concepts/learnings/) — review, identification, and promotion to shared knowledge - [Work with knowledge bases](/guides/working-with-knowledge-bases/)