---
title: "Tools"
description: "MCP tool surface for reading and writing project memories."
---

> Documentation Index
> Fetch the complete documentation index at: https://machine-memory.jfa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

After [enabling MCP](/docs/mcp/enable) and connecting a client to `/mcp`, these tools are available.

## Safety model

| Kind     | Tools                                                                                    | Wrong `repository` slug                 |
| -------- | ---------------------------------------------------------------------------------------- | --------------------------------------- |
| Read     | `memory_suggest`, `memory_query`, `memory_get`, `memory_list`                            | Empty or not-found; nothing lost        |
| Maintain | `memory_doctor`, `memory_stats`, `memory_gc`                                             | Empty report; nothing lost              |
| Check    | `memory_verify`, `memory_diff`                                                           | Not-found message; nothing lost         |
| Measure  | `memory_size`                                                                            | N/A (no repository)                     |
| Discover | `list_repositories`                                                                      | N/A                                     |
| Write    | `memory_add`, `memory_update`, `memory_deprecate`, `memory_delete`, `memory_delete_many` | Required exact `owner/name`; no default |

Call `list_repositories` before writes when the slug is not certain. Derive `owner/name` from `git remote get-url origin` when it matches a known entry.

## Tool reference

| Tool                 | Purpose                                                                  |
| -------------------- | ------------------------------------------------------------------------ |
| `list_repositories`  | List slugs with total, active, deprecated, and superseded counts         |
| `memory_suggest`     | File-scoped lookup: FTS over path terms + directory neighborhood         |
| `memory_query`       | Keyword, semantic, or hybrid search with filters                         |
| `memory_get`         | Fetch one memory by numeric id                                           |
| `memory_list`        | List memories with filters and offset pagination                         |
| `memory_doctor`      | Audit duplicates, status expiry, types, tags, and refs                   |
| `memory_stats`       | Summarize status, type, certainty, tag, and age distributions            |
| `memory_gc`          | Preview expired status memories; never mutates                           |
| `memory_verify`      | Check an inferred fact against a memory (consistent / conflict)          |
| `memory_diff`        | Diff proposed content against a memory (terms added / removed)           |
| `memory_size`        | Preflight embedding budget without writing                               |
| `memory_add`         | Create a memory (or upsert via `upsert_match`)                           |
| `memory_update`      | Update content or metadata by id (or `match`)                            |
| `memory_deprecate`   | Mark up to 100 explicit ids deprecated or superseded, preserving history |
| `memory_delete`      | Permanently delete one memory and its vector                             |
| `memory_delete_many` | Permanently delete up to 100 explicit ids and their vectors              |

Every tool that takes `repository` expects `owner/name`. Rows live in D1; embeddings sync to Vectorize on write. `memory_query`, `memory_list`, and `memory_suggest` accept a `tags` substring filter alongside `status` / `memory_type` / `certainty`.

### Pagination and repository counts

`memory_list` and `list_repositories` return `count`, `total_count`, `offset`, `limit`, and `has_more`. Continue with `offset + count` while `has_more` is true. `list_repositories` entries include `slug`, `total`, `active`, `deprecated`, and `superseded`, so a cleanup can be scoped without blind per-repository queries.

### Maintenance

- `memory_doctor` audits active memories and returns typed findings with every involved id. Findings are suggestions: review them semantically before writing.
- `memory_stats` reports aggregate status, type, certainty, tag, and age data for one repository.
- `memory_gc` is always a dry run. It returns active status memories whose `expires_after_days` window has elapsed.
- `memory_deprecate` accepts `ids` and optional `superseded_by`. It preserves the records and re-syncs their vector metadata.
- `memory_delete_many` accepts one to 100 explicit `ids`. It is permanent and echoes `deleted_from`, `deleted_ids`, and `not_found`.

### Suggest

`memory_suggest` ports the CLI `suggest` command for the pre-edit scan. Pass comma-separated `files` plus an optional extra `query`; it returns the derived path terms, the directory neighborhood (`tags` / `paths` hints), and scored results.

### Verify and diff

`memory_verify` (`{ repository, id, fact }`) and `memory_diff` (`{ repository, id, content }`) port the CLI `verify` / `diff` commands (term similarity plus negation check). Use them before `memory_update` when an inference may conflict with a stored memory.

### Writes

`memory_add` accepts `upsert_match` (with `force` and `upsert_threshold`, default score 32 alongside similarity ≥ 0.62): a strong match updates in place, otherwise a new record is created, and a weak match refuses unless forced. New records echo `potential_conflicts` so near-duplicates stay visible.

`memory_update` targets `id` or `match` (best active full-text hit, echoed back as `matched`); only provided fields change. It also accepts `expires_after_days` (status memories only). Prefer `memory_deprecate` for dedicated deprecation and supersession workflows.

### Search

`memory_query` `mode`:

| Mode       | Behavior             |
| ---------- | -------------------- |
| `keyword`  | D1 full-text index   |
| `semantic` | Vectorize embeddings |
| `hybrid`   | Merge both (default) |

Filters `status`, `memory_type`, and `certainty` use the same enums as the CLI.

### Writes

Typical fields on `memory_add` / `memory_update`:

- `content` (required on add) — put commands, paths, and identifiers in the first sentence
- `tags` — comma-separated, e.g. `area:cli,topic:backend,kind:decision`
- `context` — optional supporting text
- `memory_type` — `decision`, `convention`, `gotcha`, `preference`, `constraint`, `reference`, `status`
- `certainty` — `verified`, `inferred`, `speculative`
- `status` — `active`, `deprecated`, `superseded_by`
- `expires_after_days` — only valid when `memory_type` is `status`

## Embedding size budget

Composed embedding text (content + optional tags/context + type/status/certainty labels) must stay within the Worker budget:

```text
UTF-8 bytes + 2 ≤ 512
```

Same conservative limit the CLI enforces with `machine-memory size` and add/update `--dry-run` (the Worker cannot run the full BGE tokenizer).

- **`memory_size`** — measure without writing; over-budget responses set `isError: true` and include `over_by_bytes` / `within_budget`
- **`memory_add` / `memory_update`** — reject on flight before any D1 write when over budget

Call `memory_size` before long writes.

## Response shape

Successful writes echo scope so a wrong namespace is obvious in the transcript:

```json
// memory_add
{
  "written_to": "owner/repo",
  "id": 42,
  "memory": { },
  "size": {
"source": "bytes",
"bytes_estimate": 128,
"max_bytes_estimate": 512,
"within_budget": true,
"over_by_bytes": 0
  }
}

// memory_delete
{
  "deleted_from": "owner/repo",
  "id": 42,
  "deleted": true,
  "existed": true
}

// memory_delete_many
{
  "deleted_from": "owner/repo",
  "requested_ids": [42, 43],
  "deleted_ids": [42],
  "not_found": [43],
  "count": 1
}
```

## Agent workflow (short)

1. `list_repositories` if the slug is unknown
2. `memory_suggest` (known files) or `memory_query` / `memory_list` before code changes
3. `memory_get` for full records you will rely on
4. `memory_verify` / `memory_diff` when an inference may conflict
5. `memory_size` when content may be large
6. `memory_doctor` / `memory_stats` / `memory_gc` during maintenance
7. `memory_add` (prefer `upsert_match`) / `memory_update` (prefer `match`) for durable outcomes
8. `memory_deprecate` for obsolete records; use permanent delete tools only when intended

Install that checklist into the repo with [Init](/docs/mcp/init).

Source: https://machine-memory.jfa.dev/docs/mcp/tools/index.mdx