MCP Tools

The MCP gives your agent six ways to work with memories.

insert-memoryCopy Anchor Link

Creates one memory.

Choose the narrowest scope where the memory provides useful context. For example, a login-session cookie memory used throughout authentication applies to ["apps/web/auth"]. Use ["."] only for context useful across the whole repository.

Example:

{
  "roots": ["/Users/adam/Desktop/acme/acme-app", "/Users/adam/Desktop/acme/acme-cli"],
  "repo": "/Users/adam/Desktop/acme/acme-app",
  "body": "Cache responses only after authentication succeeds.",
  "frontmatter": {
    "title": "Authenticated response caching",
    "scope": ["apps/web/auth"]
  }
}

Memories are automatically placed into the deepest package or repo root containing every scope path.

update-memoryCopy Anchor Link

Updates an existing memory. Omitted fields retain their values. A path-only call repairs the title folder.

Example:

{
  "roots": ["/Users/adam/Desktop/acme/acme-app", "/Users/adam/Desktop/acme/acme-cli"],
  "repo": "/Users/adam/Desktop/acme/acme-app",
  "path": "/Users/adam/Desktop/acme/acme-app/.memories/cache-responses",
  "body": "Invalidate cached responses when permissions change."
}

Changing scope can move the memory to another package or the repo root. Every update also repairs the memory folder's name to match the title, even if the title did not change.

update-memory will fail if you attempt to update a memory tagged with doNotEdit.

Memories are automatically placed into the deepest package or repo root containing every scope path.

search-memoriesCopy Anchor Link

Searches the memories.

Example:

{
  "roots": ["/Users/adam/Desktop/acme/acme-app", "/Users/adam/Desktop/acme/acme-cli"],
  "repo": "/Users/adam/Desktop/acme/acme-app",
  "query": "cache",
  "scope": ["apps/web"],
  "limit": 10
}

Ideally, search will only target parts of the repository by using a narrow scope, but it may also search the whole project.

Search reads memories from:

• descendant .memories directories
• all parents' .memories directories up to the repo root whose scope includes or overlaps with the requested scope param
• other repositories in the workspace with availableToWorkspace enabled

Search rankingCopy Anchor Link

Directory tags are the folders on the path from the memory directory to the root of the repository, such as errors and auth in .memories/errors/cache/nextjs-cache/memory.md.

During search, memory titles get a 3x boost and directory tags get a 2x boost.

delete-memoriesCopy Anchor Link

Deletes memories and their attachments.

Example:

{
  "paths": ["/Users/adam/Desktop/acme/acme-app/.memories/cache-error"]
}

Passing the path to a memory tagged with doNotDelete blocks the entire operation.

Nested memories (anti-pattern) must be selected explicitly when deleting their parent folder.

Paths may span multiple Git repositories within the workspace.

upvote-memoriesCopy Anchor Link

This feature requires pruning to be enabled.

Upvotes useful memories. Upvotes requested by the user are recorded as human. Memories that help the agent produce a reply receive agent upvotes. Memories in repositories with pruning enabled receive upvotes; the rest are reported as skipped because pruning is disabled.

Example:

{
  "paths": ["/Users/adam/Desktop/acme/acme-app/.memories/cache-error"],
  "actor": "agent"
}

prune-memoriesCopy Anchor Link

This feature requires pruning to be enabled.

Lists expired memories within repo, excluding the ones tagged with doNotDelete.

When candidates exist, the agent is instructed to read each memory and check its relevance against the code, then suggest which to delete or keep.

Example:

{
  "repo": "/Users/adam/Desktop/acme/acme-app"
}