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), no_strong_match, and scored results. A result is strong only when the memory names a suggested file by full path or specific file name.

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. A content or status change also returns dropped (identifiers and sentences the new content lost) and review_candidates (other active memories that may rely on the old premise). memory_deprecate returns review_candidates too, and memory_diff returns dropped before anything is written. It also accepts expires_after_days (status memories only). Prefer memory_deprecate for dedicated deprecation and supersession workflows.

History and recovery

memory_history takes { repository, id, limit?, offset? } and returns complete previous snapshots, newest first. It includes current_update_count and the usual pagination fields. Review a snapshot, then call memory_restore with { repository, id, revision_id, expected_update_count }. Set expected_update_count to the response’s current_update_count, not the historical row’s count. A newer write causes a conflict instead of being overwritten.

Restore preserves the ID and repository, increments the current update count, refreshes updated_at, and marks last_updated_by as restore. It restores the other metadata, including refs, replacement, and expiry; status expiry starts from the fresh update time. The replaced state becomes another history entry, so a restore can itself be undone.

Snapshots are never embedded or included in memory searches. Only the restored canonical row queues vector synchronization: active rows are embedded, while inactive rows have their vectors removed. No migration-time reindex is needed. History starts at migration 0004; earlier overwrites cannot be recovered. There is no automatic pruning, and existing import/export and local-to-remote transfers do not carry history. Permanent deletion also purges history. See history and restore for CLI usage and constraints.

Search

memory_query mode:

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

Search results and full rows include evidence and validation_gaps. Neither is embedded, so they do not affect semantic search or the size budget.

memory_query returns { count, no_strong_match, results }. Each result includes score, which only ranks within the response, plus absolute relevance fields: match_strength (strong, weak, or none), term_coverage, and exact_matches. Strong results come first. When no_strong_match is true, treat the results as loosely related candidates. The thresholds match the CLI; see query match strength.

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; verified requires a non-empty evidence
• evidence — array of user_requirement, observed_implementation, verified_mechanism, tested_behavior; on update it replaces the stored array and [] clears it
• validation_gaps — array of up to 16 short strings naming what is still unconfirmed, such as user intent or untested platforms
• 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.