Montycat MCP - Shared Memory for AI Agents

Wait until memory CHANGES — returns the moment another agent or session writes, updates, or deletes something in this memory. This is a live subscription to the database, not a poll: it sleeps until a change actually happens and then returns immediately. Use it to coordinate with other agents sharing a scope ("tell me when someone adds to our shared memory"), or to confirm a write from another session landed. Do NOT call it in a tight loop as a substitute for searching — to *find* things, use montycat_semantic_search. Returns `{changes: [...], next_seq, oldest_seq, cursor_expired, timed_out}`. Each change is `{seq, key, event, value}` where event is "inserted" (covers create and update) or "removed". Pass the returned `next_seq` back as `since_seq` on the next call to resume exactly where you left off. If the bounded buffer has discarded part of that history, `cursor_expired` is true and `oldest_seq` identifies the earliest retained record. Args: scope: Owner/user id whose memory to watch (keyspace mem_<scope>). Use "shared" for the common keyspace — the usual choice when coordinating between agents. keyspace: Explicit keyspace override (advanced; bypasses scope). timeout_sec: How long to wait before giving up (default 30). On timeout the result is empty with `timed_out: true` — that is a normal outcome, not an error. since_seq: Resume cursor from a previous call. Omit on the first call to watch only for changes from now on.

Delete snapshot files for one existing in-memory keyspace. This is destructive to the keyspace's snapshot history but does not delete its currently loaded in-memory records. Montycat performs the final authorization check. Args: keyspace: Explicit in-memory keyspace whose snapshots are cleaned.

Create a new memory namespace using the configured owner's authority. A delegated owner can create a keyspace when its governance policy grants `provision-keyspace` for the requested store, storage type, and semantic model, but its store must already exist. With superowner credentials, the engine creates a missing configured store and this first keyspace together in the same provisioning request. The engine remains the final authorization boundary. Args: keyspace: Name of the keyspace to create. storage: Preferred storage type: "persistent" or "inmemory". Defaults to "persistent". semantic: Enable semantic search for this keyspace after creation. semantic_model: Optional embedding model: "minilm", "bge-small", "bge-base", or "e5-small". Supplying a model implies semantic=True. persistent: Deprecated compatibility option. True maps to storage="persistent"; False maps to storage="inmemory". cache: Optional cache size in MB (persistent only; min/default 10). compression: Enable compression at keyspace creation (persistent only). This setting is immutable; migrate to a new keyspace to change it later.

Disable semantic search for one explicit keyspace. Stored vectors are retained by default so re-enabling can resume without a full rebuild. Set `drop_vectors` only when intentionally clearing vectors, such as before changing embedding models. The engine enforces all governance authority and explicit denials. Args: keyspace: Explicit keyspace to unenroll. store: Target store. Defaults to the configured store. drop_vectors: Also delete stored vectors for this keyspace.

Enroll a keyspace for caller-supplied embeddings instead of text embedding.

Enable semantic search for one explicit keyspace. The engine enforces `manage-semantic`, creator authority, explicit denials, and allowed-model constraints. Existing records are backfilled by the engine. This tool never enables semantic search database-wide. Args: keyspace: Explicit keyspace to enroll and backfill. store: Target store. Defaults to the configured store. semantic_model: Optional model: "minilm", "bge-small", "bge-base", or "e5-small". Omit to use the engine/policy default. field: Optional JSON field to embed instead of the whole stored value.

Delete a stored record from memory by key or custom key. Args: keyspace: Memory namespace (defaults to the configured one). key: Montycat-generated key to delete. custom_key: Custom key to delete. wait_for_index: For persistent keyspaces, wait for secondary indexes before returning. Defaults to the engine setting.

Install the Montycat engine on THIS computer, then start it. Call this only when memory tools report that no engine is running and the user has agreed to install one. Tell them what it does first: it downloads the Montycat Semantic package (~18 MB) and opens your operating system's installer, which asks for an administrator password. On Linux it runs the documented APT installation with `sudo`. Refuses when MONTYCAT_URI is set or the configured host is not this machine — Montycat MCP is pointed at an engine elsewhere, and installing a local one would create a second database and write memories where nobody is looking. Does nothing if an engine is already reachable. Not needed when Docker is available: engine startup falls back to a container automatically, with no prompt.

List schemas enforced on a keyspace, including field data types. Use this before a structured write or retrieval when the target keyspace's required fields or types are unknown. For retrieval, it helps construct correctly typed field filters. This inspection is read-only and never creates a missing keyspace. Args: keyspace: Explicit keyspace name. Takes precedence over scope. scope: Owner/user memory scope (maps to its configured keyspace). Use "shared" for the common keyspace. When both inputs are omitted, the configured default keyspace is inspected.

List the available memory stores and keyspaces on this Montycat engine.

Browse stored memories — enumerate what is remembered, not search by meaning. Returns up to `limit` records with their keys. Use this to review or list memory; for meaning-based recall use montycat_semantic_search, and for exact lookups use montycat_recall. Args: keyspace: Memory namespace (defaults to the configured one). limit: Max records to return (default 25). recent: Return the most recently written records first (default True). Persistent keyspaces order by key, which is a strict write order; in-memory keyspaces have no ordered read, so there the bias stays approximate (by storage volume) and falls back to a full scan when the latest volume is empty. Pass False to read from the oldest record forward. timestamp_field: Native Timestamp index field constrained by since/until. Defaults to the auto-stamped `_created_at` field. since: Lower timestamp bound (ISO-8601). until: Upper timestamp bound (ISO-8601).

Explain whether the configured owner may perform a proposed action. This is a read-only policy check for planning and diagnostics; executing the action still requires a separate tool call and fresh engine authorization. The explanation identifies applicable grants, denials, creator authority, and storage/model constraints. Args: capability: One of "provision-keyspace", "remove-keyspace", "manage-snapshots", "manage-semantic", "manage-schema", or "manage-access". store: Target store. Defaults to the configured store. keyspace: Optional target keyspace. storage: Optional keyspace type: "persistent", "inmemory", or "distributed". semantic_model: Optional model constraint: "minilm", "bge-small", "bge-base", or "e5-small".

View governance history visible to the configured owner. This is read-only and owner-scoped by the authenticated Montycat credential. It can show when authority was delegated, denied, revoked, or transferred without allowing the MCP caller to select another owner. Args: store: Optional store filter. Defaults to the configured store. keyspace: Optional keyspace filter.

View the configured owner's effective Montycat governance policy. This is read-only. It reports the authenticated owner's effective grants, denials, accessible and owned keyspaces, automatic creator capabilities, provisioning constraints, and policy health. The engine filters the result and remains the authorization boundary. Args: store: Optional store to inspect. Defaults to the store configured by MONTYCAT_URI or MONTYCAT_STORE.

Recall memory by exact key or by field filter (not by meaning). Provide `key`/`custom_key` to fetch a single record, or `filters` (a map of field -> value) to look up all records matching those fields. For meaning-based recall use montycat_semantic_search instead. Args: keyspace: Memory namespace (defaults to the configured one). key: Montycat-generated key to fetch. custom_key: Custom key to fetch. filters: Field equality filters, e.g. {"user": "alice", "topic": "billing"}. limit: Max results for a filter lookup (default 25).

Replace an enrolled keyspace's text embedding model and backfill it. This clears its current vectors, then has the engine rebuild them. Use `montycat_semantic_status` to observe the resulting configuration.

Store a fact or record in memory; it is embedded and indexed automatically. Later recall it by meaning with montycat_semantic_search, or by key with montycat_recall. Returns the generated key in `payload`. Every record is auto-stamped with an indexed `_created_at` (UTC ISO-8601) unless the value already carries one — this powers time-range recall (`since`/`until` on montycat_semantic_search). Top-level fields are indexed, so they can be used as `filters` in hybrid search (e.g. store `{"project": "x", ...}`, later filter on it). Args: value: The record to store (a JSON object). scope: Owner/user id to store under (that owner's private memory, keyspace mem_<scope>). Use "shared" for the common keyspace. keyspace: Explicit keyspace override (advanced; bypasses scope). custom_key: Optional stable key to store under (for later exact recall/update). timestamp: Index a `_created_at` for time-range recall. Defaults to MONTYCAT_AUTO_TIMESTAMP (on). Pass False to skip the server-side timestamp parse when this memory will never be recalled by time. wait_for_index: For persistent keyspaces, wait until secondary indexes have caught up before returning. Defaults to the engine setting; use True when an immediate filtered/semantic recall must see this write. vector: Optional precomputed embedding for this record. It must match the keyspace's enrolled embedding profile.

Store many memories at once; all are embedded and indexed automatically. Args: values: A list of records (JSON objects) to store. keyspace: Memory namespace (defaults to the configured one). timestamp: Index a `_created_at` on each record for time-range recall. Defaults to MONTYCAT_AUTO_TIMESTAMP (on). Pass False for large imports that will never be recalled by time — it skips a server-side timestamp parse per record. wait_for_index: For persistent keyspaces, wait for secondary indexes before returning. Defaults to the engine setting.

Permanently remove a memory namespace using the owner's authority. This is a destructive lifecycle operation. Before removal Montycat MCP closes the keyspace's live watch and releases MCP resource-subscription ownership so the engine cannot deadlock on a lingering subscriber. The engine then enforces `remove-keyspace`, creator authority, and explicit denials. Args: scope: Owner/user scope to remove (maps to keyspace mem_<scope>). Use "shared" for the configured shared keyspace. keyspace: Explicit keyspace override (advanced; bypasses scope).

Search stored memory by MEANING, by KEYWORD, or both. Use this to recall relevant facts, documents, or past context for RAG and agent memory. Returns the top matches ranked by relevance, each with its key, a score, and the stored value. Ranking modes (`mode`): - "semantic" (default) — vector similarity. Finds a memory whose wording differs from the query. Scores are cosine similarity in [-1, 1]. - "keyword" — BM25 over the stored text. Use it when the query contains an exact term that must appear: an identifier, error code, or file name. BM25 scores are unbounded and comparable only within one query. - "hybrid" — runs both and fuses them with reciprocal rank fusion. The safest default when a query mixes meaning with an exact term. Scores are normalized to [0, 1]. Keyword and hybrid need a Montycat Semantic engine >= 1.3.4; older engines reject the request rather than silently returning semantic-only results. Narrowing is separate from ranking: `filters`, `since`, and `until` restrict WHICH memories are ranked — a hard AND over indexed fields — and never change the order within that set. Combine them freely: "what did we decide about the index" + `since` yesterday + `filters={"project": "montycat"}` is one call. A filter matching nothing returns []. Args: query: Natural-language description of what to recall. May be empty when `vector` supplies a precomputed query embedding. mode: Ranking strategy — "semantic", "keyword", or "hybrid". vector: Optional precomputed query embedding, for the vector half of "semantic" and "hybrid". It must match the keyspace's enrolled embedding space and dimensions; when set, the engine does not embed `query`. scope: Owner/user id to scope recall to (searches only that owner's memory, keyspace mem_<scope>). Use "shared" for the common keyspace. keyspace: Explicit keyspace override (advanced; bypasses scope). limit: Max number of results (default 5). min_score: Optional relevance floor; drops weak matches. The valid range follows the mode: [-1, 1] semantic, [0, 1] hybrid, >= 0 keyword. filters: Optional metadata constraints, e.g. {"project": "x"} — only memories whose indexed fields equal these values are ranked. timestamp_field: Native Timestamp index field to constrain, e.g. "event_time". Defaults to the auto-stamped "_created_at". Use the index field name, not "timestamps.event_time". The field must be stored as a Timestamp index; an ordinary JSON string field is not sufficient. since: Lower time bound for timestamp_field (ISO-8601, UTC). until: Upper time bound for timestamp_field (ISO-8601, UTC). Bounds use the SDK's native Timestamp after/before/range queries. Do not also put timestamp_field in filters when supplying bounds.

Read the engine's actual semantic configuration and backfill state. Pass both `store` and `keyspace` for one keyspace. Omitting both asks for the database-wide view, which may require superowner authority.

Start scheduled snapshots for one existing in-memory keyspace. Montycat enforces `manage-snapshots`, creator authority, and explicit denials. If the response says "Snapshot rate is not set", snapshot scheduling is not configured on the engine; that is an environmental configuration error, not an authorization denial. This tool cannot alter the global snapshot rate. Args: keyspace: Explicit in-memory keyspace to snapshot.

Stop scheduled snapshots for one existing in-memory keyspace. Existing snapshot files are retained. Montycat performs the final authorization check. Args: keyspace: Explicit in-memory keyspace whose snapshot schedule stops.

Revise an existing memory in place (memory is mutable). Use this when a stored fact changes — a corrected value, an updated preference — instead of storing a duplicate. Only the fields you pass are changed. Identify the record by `key` or `custom_key`. Args: updates: Fields to change, e.g. {"status": "resolved"} or {"name": "Alice"}. keyspace: Memory namespace (defaults to the configured one). key: Montycat-generated key of the record to update. custom_key: Custom key of the record to update. wait_for_index: For persistent keyspaces, wait for secondary indexes before returning. Defaults to the engine setting.

Change the cache capacity of an existing persistent keyspace. Args: cache: Cache capacity in MB. Must be a positive integer. scope: Owner/user scope (maps to keyspace mem_<scope>). Use "shared" for the configured shared keyspace. keyspace: Explicit keyspace override (advanced; bypasses scope).