---
title: "Memory"
url: "https://docs.mekodata.ai/concepts/memory/"
---

# Memory

Long-term memory for AI agents, and how to add, search, and manage it

Memory in Meko gives agents persistent, long-term recall of facts, preferences, and decisions extracted from conversations. Unlike conversation history, which stores raw messages, memory stores the focused facts that an LLM extracts from interactions.

To choose between a memory, a knowledge-base file, and an artifact, see [Where to store it](/concepts/where-to-store/).

## How it works

Whether the text comes from an explicit request or a saved conversation ([Add memories](#add-memories)), Meko:

1. Uses an LLM to extract focused, durable facts.
2. Stores the facts and their vector embeddings for retrieval.
3. Indexes the text so searches can combine semantic similarity with keyword and named-entity signals.

This hybrid retrieval helps an agent find a memory by meaning while giving extra weight to exact terms and named entities in the query.

|                      | Memory                                      | Conversation History                     |
|----------------------|---------------------------------------------|------------------------------------------|
| **What's stored**    | Extracted facts, preferences, and decisions | Raw messages (user + assistant)          |
| **How it's created** | LLM extracts from conversations             | Stored verbatim                          |
| **Search method**    | Semantic, keyword, and entity-aware ranking | Chronological lookup                     |
| **Use case**         | "Remember my preferences across sessions"   | "Show me what was said in the last chat" |

## Add memories

### Ask your agent

The simplest way to add a memory is in 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 [Client Installer](/use-meko/connect/#quick-start)) 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 is required.

Extraction is asynchronous and best-effort

Conversation-driven extraction runs after the 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

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?
```

`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. Strong keyword or entity signals can place a result above one with a higher `raw_similarity_score`. For example, the memory *"John likes bananas"* can match the exact query *"Who likes bananas?"* and the related query *"Who likes fruit?"* See [Memory retrieval](/concepts/how-meko-learns/memory-retrieval/).

## List your memories

To review your memories in a datapack, ask your coding agent in plain language. For example:

```text
List all my Meko memories in the default datapack.
```

`memory_get_all` returns a list of all your memories in the specified datapack, a page at a time, along with the total number of pages. You can request specific pages, and specify the page size. A call that omits `page` returns only the newest page. Memories written while you page, by a capture hook for example, shift rows between pages, so the list is complete only if nothing changes while you page. `promoted=true` pages through every promoted memory in the datapack instead, including other members'. An older server rejects `page` and `page_size` and returns only the newest rows.

To find a specific memory, use `memory_search` instead, or `memory_get_by_id` when you know its ID. See [memory tools](/reference/mcp-server/#memory-tools).

## 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**.

`memory_delete_by_id` deletes one memory. `memory_delete_all` removes memories written under one `agent_id`, optionally narrowed to one conversation by passing its ID as `run_id`. It deletes only your own memories under that `agent_id`, never another member's. Omitting `agent_id` deletes the `meko_agent` bucket, not every agent, and omitting `datapack_id` uses your default datapack, not the one you were discussing. It returns `deleted_count` and the scope it used. If it runs out of time, `complete` is false and the count is what it has removed so far. Call it again to continue. Deleted memories can't be recovered.

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](/concepts/how-meko-learns/learnings/).

## Next steps

- [Memory retrieval](/concepts/how-meko-learns/memory-retrieval/) — how Meko ranks memory search results
- [Learnings](/concepts/how-meko-learns/learnings/) — review, identification, and promotion to shared knowledge
- [Knowledge bases](/concepts/knowledgebase/)