Tools

After enabling MCP and connecting a client to /mcp, these tools are available.

Safety model

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

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:

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:

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:

// 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.