Polypack Memory MCP server

Persistent, adaptive memory for MCP clients.

<!-- mcp-name: io.github.imattau/polypack-mcp -->

An MCP server that exposes Polypack as persistent adaptive memory. MCP-specific tools live here; the database remains an independent dependency.

Install and run

The simplest installation is from PyPI:

python3 -m pip install 'polypack-mcp[polypack]'

For one MCP client, use the default stdio server configuration. For Claude and Codex sharing the same durable memory, install once and create a long-running user service:

polypack-mcp setup --store ~/.local/share/polypack-mcp

This starts a stateless Streamable HTTP server at http://127.0.0.1:8765/mcp/, restarts it after a failure, and prints client configuration snippets. The setup command uses systemd --user; on systems without systemd, start the server directly:

polypack-mcp --transport streamable-http --port 8765 --store ~/.local/share/polypack-mcp

In shared Streamable HTTP mode, configure both clients with the URL. Do not configure them with a command and --store, since that starts two processes competing for the same durable store.

Codex (~/.codex/config.toml):

[mcp_servers.polypack]
  url = "http://127.0.0.1:8765/mcp/"

Claude Desktop:

{
  "mcpServers": {
    "polypack": { "url": "http://127.0.0.1:8765/mcp/" }
  }
}

Debian package

The Debian package installs and starts a system-level polypack-mcp service automatically. It runs as the dedicated polypack user, stores data in /var/lib/polypack-mcp, and exposes the same local Streamable HTTP endpoint:

sudo apt install ./polypack-mcp_<version>_amd64.deb

After installation, point Claude and Codex at http://127.0.0.1:8765/mcp/. The default port can be changed in /etc/default/polypack-mcp, followed by a service restart. The service can be managed with:

sudo systemctl status polypack-mcp
sudo systemctl restart polypack-mcp

The PyPI installation remains user-managed and uses polypack-mcp setup to create a per-user service instead.

Optional semantic retrieval

The default installation uses Polypack's local graph, activation, and lexical retrieval without downloading an AI model. To enable local Qwen semantic retrieval, run:

sudo polypack-mcp embeddings setup qwen3 --system --store /var/lib/polypack-mcp

This creates a managed localhost helper, downloads Qwen once into the store's embedding cache, and reindexes existing memories. The model is not bundled in the Debian/RPM package.

The helper loads Qwen3-Embedding-0.6B in bfloat16 (~1GB resident once loaded, versus ~2.4GB in fp32) and unloads it after 15 minutes of inactivity, reloading automatically on the next request. memory_recall results include a semantic entry in scoreComponents whenever the helper is reachable, alongside lexical and activation — the three sum to the reported score. If the helper is stopped or errors, recall falls back to lexical + activation scoring automatically. Check or disable it with:

polypack-mcp embeddings status
sudo polypack-mcp embeddings disable --system --store /var/lib/polypack-mcp

For a PyPI user service, omit sudo --system and use the user store:

polypack-mcp embeddings setup qwen3

APT repository

The latest Debian package is also published to the public APT repository at https://imattau.github.io/polypack-mcp. Configure it with the repository's signing key, then install and update normally:

Shortened. The full README is on GitHub.