Polypack Memory

Persistent, adaptive memory for MCP clients.

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:

curl -fsSL https://imattau.github.io/polypack-mcp/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/polypack-mcp.gpg
echo "deb [signed-by=/usr/share/keyrings/polypack-mcp.gpg] https://imattau.github.io/polypack-mcp stable main" \
  | sudo tee /etc/apt/sources.list.d/polypack-mcp.list
sudo apt update
sudo apt install polypack-mcp

The repository is updated automatically for each v*.*.* release tag. See docs/apt-repository.md for maintainer setup instructions.

RPM package

RPM-based distributions can install from the public RPM repository:

sudo rpm --import https://imattau.github.io/polypack-mcp/rpm/RPM-GPG-KEY-polypack-mcp
sudo tee /etc/yum.repos.d/polypack-mcp.repo >/dev/null <<'EOF'
[polypack-mcp]
name=Polypack MCP
baseurl=https://imattau.github.io/polypack-mcp/rpm/
enabled=1
gpgcheck=1
gpgkey=https://imattau.github.io/polypack-mcp/rpm/RPM-GPG-KEY-polypack-mcp
EOF
sudo dnf install polypack-mcp

The matching .rpm asset is also attached to the GitHub release:

sudo dnf install ./polypack-mcp-<version>-1.x86_64.rpm

The RPM package provides the same systemd service, store location, localhost Streamable HTTP endpoint, and Python 3.12 requirement as the Debian package.

Run manually

pip install -e '.[polypack]'
polypack-mcp --store ./polypack-data

The server exposes seventeen focused tools: memory_store, memory_get, memory_update, memory_list_contexts, memory_delete, memory_recall, memory_context, memory_feedback, memory_suppress, memory_supersede, memory_consolidate, memory_link, memory_unlink, memory_thread, memory_store_batch, memory_link_batch, and graph_query. It also publishes context, active-memory, schema, stats, and agent workflow guidance resources under polypack://.

Memory classes are entity, episodic, procedural, and semantic. Store project or user preferences as procedural memories; preference is not a separate memory class.

When using a durable Polypack store, mutating operations checkpoint immediately and the server flushes the store during shutdown.

Retrieval tools return {items, metadata}. Metadata includes candidate and excluded counts, context matches, score components, fallback behavior, the retrieval version, and selection statistics. memory_context uses estimated tokens (ceil(content characters / 4), minimum one) as its token_budget. An item is never returned if it would exceed the remaining budget; budgets less than or equal to zero are rejected. Context is a soft preference: matching memories are preferred and unscoped global memories may be used as fallback. Pass strict_context: true for isolation. An empty isolated result reports reason: "no_context_match" and the searched context.

memory_recall can optionally hydrate related graph memories in the same call:

{
  "query": "identity cache fix",
  "context": "cross-agent",
  "include_neighbors": true,
  "edge_types": ["RESPONDS_TO"],
  "depth": 2,
  "neighbor_limit": 3,
  "limit": 20,
  "token_budget": 4000
}

Neighbor traversal is opt-in and bounded. limit caps the total response and neighbor_limit caps hydrated neighbors; metadata reports moreNeighborsAvailable when additional eligible neighbors were found. Neighbor items include their distance and connecting relationship metadata. Use memory_link with the default RESPONDS_TO relationship for handoffs, reviews, and fixes that address an earlier memory. Graph edges are authoritative for relationships; use graph_query(operation="relationship_diagnostics") to find legacy provenance.responds_to values that are not backed by edges. See polypack://help/workflow for the agent-facing workflow.

Feedback is activation feedback: useful=true reinforces a memory and useful=false provides negative retrieval feedback. Responses expose activation before and after plus whether learned weights changed. Supersession and consolidation materialize SUPERSEDES, SUPERSEDED_BY, and CONSOLIDATED_FROM graph edges.

Use memory_get for exact ID lookup and memory_update for mutable fields (context, confidence, provenance, and metadata). Content changes should use memory_supersede so history remains intact. Use memory_unlink to correct a relationship and memory_list_contexts to discover namespaces. memory_delete is permanent, requires confirm=true, and supports an optional revision check; prefer memory_suppress when retaining history is useful.

Pass --store to open a durable Polypack directory. Without it, the server uses the in-memory reference backend, which is convenient for smoke tests. The polypack extra requires polypack-db>=3.3.1 and uses its native ActivationEngine.working_memory selector for context assembly.

Development

pip install -e '.[dev]'
pytest

The test suite includes an MCP client/server protocol smoke test covering tool discovery, memory storage, recall, and resource reads.

Documentation

• Getting started
• Operations and configuration
• Troubleshooting