memocat-mcp 0.4.0__tar.gz

memocat_mcp-0.4.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# uv
+uv.lock
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# tooling
+.pytest_cache/

memocat_mcp-0.4.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to MemoCat MCP are documented here.
+
+## 0.4.0 — Unreleased
+
+First public release (planned).
+
+### Added
+
+- Nineteen MCP tools for semantic memory, exact recall, bulk operations,
+  keyspace lifecycle, governance, semantic management, snapshots, and live
+  memory-change watches.
+- Hybrid semantic retrieval with metadata and indexed time-range filtering.
+- Automatic `_created_at` timestamps for temporal agent memory.
+- Persistent, in-memory, private-scope, and shared-scope memory routing.
+- MCP resources with live `resources/updated` notifications.
+- Delegated-owner policy view, explanation, history, provisioning, removal,
+  semantic management, and snapshot management.
+- Revocation-aware authorization leases that close watches and purge buffered
+  data after access loss.
+- Native engine discovery and verified platform-package bootstrap, with Docker
+  fallback.
+- Precomputed-vector memory writes and queries, external-vector profile
+  enrollment, semantic status inspection, and semantic re-embedding.
+
+### Security
+
+- Engine-enforced cross-owner isolation and a 24-scenario live governance
+  acceptance matrix.
+- Safe keyspace removal that releases subscriptions before engine teardown.
+- Mandatory SHA-256 verification for downloaded engine packages.

memocat_mcp-0.4.0/Dockerfile

@@ -0,0 +1,17 @@
+# syntax=docker/dockerfile:1
+# MCP is a stdio server, not an HTTP service. Run this image with `-i` (or via
+# `docker compose run -T mcp`) and keep Montycat in the companion service.
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    MEMOCAT_AUTOSTART=off
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY memocat_mcp ./memocat_mcp
+
+RUN pip install --no-cache-dir .
+
+ENTRYPOINT ["memocat-mcp"]

memocat_mcp-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MontyGovernance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memocat_mcp-0.4.0/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.5
+Name: memocat-mcp
+Version: 0.4.0
+Summary: MCP server for self-hosted AI agent memory, semantic search, vector RAG, and Montycat.
+Project-URL: Homepage, https://montygovernance.com
+Project-URL: Documentation, https://montygovernance.com/docs
+Project-URL: Repository, https://github.com/MontyGovernance/meow_memory_mcp
+Project-URL: Issues, https://github.com/MontyGovernance/meow_memory_mcp/issues
+Project-URL: Changelog, https://github.com/MontyGovernance/meow_memory_mcp/blob/main/CHANGELOG.md
+Author: MontyGovernance
+Maintainer: MontyGovernance
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-memory,ai-agents,ai-memory,chatgpt,claude,claude-desktop,cursor,data-governance,embeddings,fastmcp,llm,long-term-memory,mcp,mcp-server,memory-server,model-context-protocol,montycat,nosql,rag,retrieval-augmented-generation,self-hosted,semantic-search,vector-database,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<2,>=1.2.0
+Requires-Dist: montycat<2,>=1.2.2
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MemoCat MCP Server — Self-Hosted AI Agent Memory and Vector RAG
+
+[![PyPI](https://img.shields.io/pypi/v/memocat-mcp.svg)](https://pypi.org/project/memocat-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/memocat-mcp.svg)](https://pypi.org/project/memocat-mcp/)
+[![License](https://img.shields.io/github/license/MontyGovernance/meow_memory_mcp.svg)](https://github.com/MontyGovernance/meow_memory_mcp/blob/main/LICENSE)
+
+**MemoCat is a self-hosted MCP memory server for Claude Desktop, Cursor,
+ChatGPT integrations, and autonomous AI agents.** It gives MCP clients private,
+persistent, semantically searchable long-term memory. `memocat-mcp` is a
+[Model Context Protocol](https://modelcontextprotocol.io) server for
+[Montycat](https://montygovernance.com), combining AI agent memory, semantic
+search, vector RAG, and NoSQL storage in one self-hosted service.
+
+Memories are embedded on-device and recalled by meaning, metadata, timestamp,
+or exact key. No cloud vector database, external embedding API, or per-query
+bill.
+
+## Features
+
+- Self-hosted long-term memory for MCP-compatible AI agents.
+- Semantic vector search with metadata and time-range filtering for RAG.
+- Persistent memory, in-memory working spaces, bulk writes, updates, and deletion.
+- Real-time memory-change subscriptions without database polling.
+- Multi-agent scopes, shared memory, delegated-owner governance, and policy explanations.
+- Keyspace lifecycle, semantic-model controls, snapshots, and revocation-safe watch buffers.
+- One-command `uvx memocat-mcp` entry point with native/Docker engine bootstrap.
+
+## Why
+
+LLM agents forget context between runs. MemoCat stores each fact in Montycat,
+embeds and indexes it automatically, and retrieves relevant memories through 22
+agent-readable MCP tools. It is both a retrieval layer for RAG and a durable
+memory layer for autonomous agents.
+
+## Quick start
+
+```bash
+uvx memocat-mcp
+```
+
+MemoCat reuses a configured Montycat Semantic engine or attempts the supported
+native/Docker bootstrap path. For an existing engine:
+
+```bash
+export MONTYCAT_URI="montycat://memory-agent:password@localhost:21210/memories"
+uvx memocat-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `memocat_semantic_search` | Recall by **meaning** (vector kNN), with text or a supplied query vector. |
+| `memocat_remember` | Store a fact/record; embedded automatically or indexed with a supplied vector. |
+| `memocat_remember_bulk` | Store many memories at once. |
+| `memocat_recall` | Fetch by exact key or by field filter. |
+| `memocat_list_memories` | Browse / list stored memories (optionally most-recent first). |
+| `memocat_update` | Revise a memory in place — memory is mutable. |
+| `memocat_forget` | Delete a stored record. |
+| `memocat_list_keyspaces` | Discover available memory namespaces. |
+| `memocat_create_keyspace` | Provision a new memory namespace. |
+| `memocat_remove_keyspace` | Permanently remove an authorized memory namespace with safe watch cleanup. |
+| `memocat_enable_semantic` | Enable semantic search and backfill one authorized keyspace. |
+| `memocat_enable_external_vectors` | Enroll one keyspace for caller-supplied vectors and a named embedding space. |
+| `memocat_semantic_status` | Inspect semantic configuration and backfill state. |
+| `memocat_reembed_semantic` | Replace an enrolled text embedding model and backfill the keyspace. |
+| `memocat_disable_semantic` | Disable semantic search for one authorized keyspace. |
+| `memocat_start_snapshots` | Start scheduled snapshots for one authorized in-memory keyspace. |
+| `memocat_stop_snapshots` | Stop scheduled snapshots for one authorized in-memory keyspace. |
+| `memocat_clean_snapshots` | Delete snapshot files for one authorized in-memory keyspace. |
+| `memocat_policy_view` | View the configured owner's effective governance policy and constraints. |
+| `memocat_policy_explain` | Explain whether a proposed governed action is allowed and why. |
+| `memocat_policy_history` | View governance history visible to the configured owner. |
+| `memocat_await_memory_change` | **Wait for memory to change** — returns the moment another agent or session writes. Live subscription, not polling. |
+
+## Real-time memory watch
+
+Other memory servers can only be polled: ask again, and again, in case something
+changed. Montycat has **native live subscriptions**, so this one pushes.
+
+```
+agent B: memocat_await_memory_change(scope="shared", timeout_sec=60)
+                    ⏳ sleeps — no polling, no wasted tokens
+agent A: memocat_remember({"text": "the deploy key rotated"}, scope="shared")
+agent B: ← returns in milliseconds with the key, the value, and the event
+```
+
+Two agents, one shared scope, one notices what the other just learned. Pass the
+returned `next_seq` back as `since_seq` to resume exactly where you left off —
+changes that happen between calls are buffered, not lost.
+
+Memory namespaces are also exposed as MCP **resources**
+(`memocat://memory/<keyspace>`) with `resources.subscribe` support, so clients
+that implement resource subscriptions get `notifications/resources/updated`
+pushed to them as well. Both surfaces share one engine subscription.
+
+Subscriptions open on demand and close when idle
+(`MONTYCAT_WATCH_IDLE_TIMEOUT`), so users who never watch pay nothing.
+
+## Requirements
+
+- Python 3.10+ through `uv` / `uvx`.
+- Access to a **Montycat Semantic** engine. `uvx memocat-mcp` first reuses an
+  existing engine, then attempts the supported native/platform installation
+  path, and finally falls back to Docker. Semantic search is enabled by default
+  in the Semantic edition.
+
+  To start the engine manually with Docker, pick the tag for your CPU—the tag
+  carries the architecture:
+
+  **Apple Silicon (M1/M2/M3/M4) — use `arm64-semantic`:**
+  ```bash
+  docker run -d --name montycat -p 21210:21210 -p 21211:21211 \
+    -e MONTYCAT_SUPEROWNER="admin" -e MONTYCAT_PASSWORD="change-me" \
+    -v montycat_data:/var/lib/.montycat \
+    montygovernance/montycat:arm64-semantic
+  ```
+
+  **Intel / AMD (x86_64) — use `semantic`:**
+  ```bash
+  docker run -d --name montycat -p 21210:21210 -p 21211:21211 \
+    -e MONTYCAT_SUPEROWNER="admin" -e MONTYCAT_PASSWORD="change-me" \
+    -v montycat_data:/var/lib/.montycat \
+    montygovernance/montycat:semantic
+  ```
+
+  > On Apple Silicon the plain `semantic` tag is the amd64 image and runs under
+  > emulation, where the embedding runtime's warm-up crashes. Use
+  > `arm64-semantic` — a native build, not a workaround. Unsure which you have?
+  > `uname -m` prints `arm64` on Apple Silicon and `x86_64` on Intel.
+
+  Port `21211` is the subscription server and is required for
+  `memocat_await_memory_change` (real-time watch); without it the other tools
+  still work.
+
+## Docker Compose deployment
+
+Use Compose when you want a reproducible local deployment with a persistent
+Semantic engine and an MCP container on the same private Docker network. Docker
+is optional when you already manage a reachable Montycat server.
+
+Create a `.env` file beside `compose.yaml`:
+
+```dotenv
+MONTYCAT_USERNAME=admin
+MONTYCAT_PASSWORD=replace-with-a-strong-password
+MONTYCAT_STORE=memories
+# Apple Silicon: arm64-semantic. Intel/AMD64: semantic.
+MONTYCAT_IMAGE_TAG=semantic
+```
+
+Start the engine and build the MCP image:
+
+```bash
+docker compose up -d montycat
+docker compose build mcp
+```
+
+The image installs the released `montycat>=1.2.2,<2` Python client declared in
+the package metadata.
+
+The engine data is stored in the named `montycat_data` volume. Ports `21210`
+and `21211` are published for debugging and external clients; the MCP container
+uses the private `montycat:21210` network address. Credentials are passed as
+separate environment variables, so passwords with URL-special characters need
+no URL encoding. Port `21211` carries live subscription traffic for
+`memocat_await_memory_change`.
+
+MCP uses stdio, so do **not** run it as a web service. Configure a desktop MCP
+client to invoke the Compose service on demand:
+
+```json
+{
+  "mcpServers": {
+    "memocat": {
+      "command": "docker",
+      "args": [
+        "compose",
+        "-f", "/absolute/path/to/montycat_mcp/compose.yaml",
+        "run", "--rm", "-T", "mcp"
+      ]
+    }
+  }
+}
+```
+
+For Apple Silicon set `MONTYCAT_IMAGE_TAG=arm64-semantic` in `.env`; the plain
+`semantic` image is AMD64. Stop the stack with `docker compose down`; include
+`-v` only when you intentionally want to erase persisted memories.
+
+### Engine auto-start
+
+MemoCat first reuses an engine already reachable through `MONTYCAT_URI` or the
+host/port settings. If none is running, it looks for an installed
+`montycat_bin` and then attempts the official platform route:
+
+| Platform | Route | If it cannot complete |
+|---|---|---|
+| macOS Apple Silicon | Discover and download the latest verified `montycat-semantic_<version>_arm64.pkg`, open Installer, and wait for installation (may prompt for admin approval) | Docker |
+| macOS Intel | No Semantic package currently published | Docker |
+| Windows x86_64 | Download verified `.msi` and invoke Windows Installer (may prompt for UAC) | Docker |
+| Linux AMD64 | Run the official one-command APT setup for `montycat-semantic` (may prompt for sudo) | Docker |
+| Other platforms | — | Docker |
+
+MemoCat asks the shared Montycat release catalog for the current Semantic
+artifact for macOS or Windows. Artifact URLs are treated as opaque, and the
+package's adjacent `.sha256` is required and verified before Installer opens;
+verified packages are cached by filename. If catalog discovery is unavailable,
+automatic native installation falls through to Docker instead of silently
+installing an older package.
+Override the URL with `MEMOCAT_INSTALLER_URL`, pin a release with
+`MEMOCAT_ENGINE_VERSION`, or adjust the Installer completion budget with
+`MEMOCAT_INSTALLER_TIMEOUT`. On Linux, set
+`MEMOCAT_APT_INSTALL_COMMAND` to use an organization-managed mirror or package
+command. ARM64 Linux goes directly to Docker because the official APT repository
+is AMD64-only. Set `MEMOCAT_AUTOSTART=off` to disable all installation/start
+attempts.
+
+## Use with Claude Desktop / Cursor
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "memocat": {
+      "command": "uvx",
+      "args": ["memocat-mcp"],
+      "env": {
+        "MONTYCAT_URI": "montycat://memory-agent:agent-password@localhost:21210/mystore"
+      }
+    }
+  }
+}
+```
+
+Use a delegated Montycat owner such as `memory-agent` for the MCP process.
+Grant that owner only the keyspace read/write and provisioning capabilities its
+agent needs. Keep the superowner credential in a separate bootstrap or
+governance-administration workflow.
+
+The read-only `memocat_policy_view`, `memocat_policy_explain`, and
+`memocat_policy_history` tools expose policy information for the authenticated
+owner. They do not accept an owner override and cannot grant, revoke, deny, or
+otherwise mutate policy. When automatic keyspace provisioning fails, MemoCat
+also requests a read-only policy explanation and appends it to the original
+engine error when available.
+
+`memocat_remove_keyspace` is destructive and remains engine-authorized. A
+delegated owner may remove a keyspace through creator authority or an explicit
+`remove-keyspace` grant unless policy contains an overriding denial. MemoCat
+closes active watches and releases resource subscriptions before requesting
+removal.
+
+Semantic management is always keyspace-scoped. The MCP server does not expose
+database-wide semantic controls; Montycat checks `manage-semantic`, creator
+authority, denials, and model allow-lists for every enable or disable request.
+
+Snapshot tools are likewise keyspace-scoped and work only with in-memory
+keyspaces. MemoCat does not expose the global snapshot-rate setting. A
+`Snapshot rate is not set` response means scheduling has not been configured
+on the engine; it is distinct from a governance denial.
+
+Active watches use short authorization leases because the current engine checks
+read authority when a subscription opens but does not terminate that connection
+after a later revocation. MemoCat revalidates against the engine's filtered
+structure view, closes the subscription on access loss, removes MCP resource
+ownership, wakes pending callers with an error, and permanently purges buffered
+changes so they cannot be replayed after access is restored.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MONTYCAT_URI` | — | `montycat://user:pass@host:port/store` (preferred; overrides the parts below) |
+| `MONTYCAT_HOST` | `127.0.0.1` | Engine host |
+| `MONTYCAT_PORT` | `21210` | Engine port |
+| `MONTYCAT_USERNAME` / `MONTYCAT_PASSWORD` | — | Credentials |
+| `MONTYCAT_STORE` | — | Store name |
+| `MONTYCAT_TLS` | `false` | Connect over TLS |
+| `MONTYCAT_DEFAULT_KEYSPACE` | `memory` | Keyspace used when a tool omits scope/keyspace |
+| `MONTYCAT_PERSISTENT` | `true` | Storage type for **newly created** keyspaces (durable vs in-memory). Existing keyspaces are auto-detected — the server binds the correct type regardless of this setting. |
+| `MONTYCAT_SCOPE` | — | Default owner/scope, applied when a tool omits `scope` |
+| `MONTYCAT_SCOPE_PREFIX` | `mem_` | Prefix for per-owner keyspaces (`mem_<scope>`) |
+| `MONTYCAT_SHARED_KEYSPACE` | `mem_shared` | The common/shared keyspace name |
+| `MONTYCAT_AUTO_PROVISION` | `true` | Auto-create a scope's keyspace on first use. Requires `provision-keyspace` authority for the configured owner and requested storage/model constraints. |
+| `MONTYCAT_AUTO_TIMESTAMP` | `true` | Stamp each memory with an indexed `_created_at`, enabling time-range recall (`since`/`until`). Costs a server-side timestamp parse per write — turn off if memories are never recalled by time. |
+| `MONTYCAT_SUBSCRIPTION_PORT` | main + 1 | Engine subscription server port (21211 by default; enabled by default) |
+| `MONTYCAT_WATCH_BUFFER` | `500` | Changes retained per watched keyspace, so changes between calls aren't lost |
+| `MONTYCAT_WATCH_IDLE_TIMEOUT` | `300` | Seconds before an unused subscription is closed |
+| `MONTYCAT_WATCH_AUTH_LEASE_SEC` | `5` | Seconds between read-authority checks for active watches. Access loss closes the subscription and purges buffered changes. |
+| `MONTYCAT_WATCH_AUTH_TIMEOUT_SEC` | `10` | Maximum seconds allowed for one watch authorization check. A failed check closes the watch safely. |
+
+`memocat_create_keyspace` works with delegated-owner credentials when policy
+grants `provision-keyspace` for the requested store, storage type, and semantic
+model. `memocat_forget` deletes one record and requires write authority for its
+keyspace. The engine makes every final authorization decision.
+
+## Memory scoping (multi-tenant)
+
+Pass `scope` (an owner/user id) to any memory tool to isolate that owner's
+memory. Because Montycat's semantic search runs per keyspace, each scope gets its
+own keyspace `mem_<scope>` — so semantic recall for one owner never sees another
+owner's memories:
+
+```
+remember(value={"fact": "..."}, scope="alice")      # -> keyspace mem_alice
+semantic_search(query="...", scope="alice")          # searches only mem_alice
+remember(value={"fact": "..."}, scope="shared")      # -> the shared keyspace
+```
+
+- **Per-owner private memory** — `scope="<owner>"` → `mem_<owner>`, auto-created
+  on first use when the configured owner has provisioning authority.
+- **Shared/common memory** — `scope="shared"` → the `MONTYCAT_SHARED_KEYSPACE`.
+- **Group memory** — use a group id as the scope (e.g. `scope="team_eng"`).
+- **Single-tenant** — set `MONTYCAT_SCOPE` once and omit `scope` per call.
+
+This maps onto Montycat's keyspace governance. In production, run one server
+instance per agent or service with delegated-owner credentials and grant only
+the provisioning and data authority it needs.
+
+**Isolation note:** `scope` is routing convenience, not authenticated identity.
+With one server instance sharing one connection, scopes provide logical
+keyspace organization. For credential-enforced isolation, run one server
+instance per owner with that owner's delegated credentials; the engine then
+denies cross-owner access. Reserve superowner credentials for bootstrap and
+governance administration.
+
+## Links
+
+- Montycat: https://montygovernance.com
+- Docs: https://montygovernance.com/docs
+- Engine on Docker Hub: https://hub.docker.com/r/montygovernance/montycat
+- Python client (PyPI): https://pypi.org/project/montycat/
+
+## License
+
+MIT.