{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/logo-lockup-dark.svg\">\n    <img src=\"docs/assets/logo-lockup.svg\" alt=\"polypack-mcp\" height=\"64\">\n  </picture>\n</p>\n\n<p align=\"center\">Persistent, adaptive memory for MCP clients.</p>\n\n<!-- mcp-name: io.github.imattau/polypack-mcp -->\n\nAn MCP server that exposes Polypack as persistent adaptive memory. MCP-specific\ntools live here; the database remains an independent dependency.\n\n## Install and run\n\nThe simplest installation is from PyPI:\n\n```sh\npython3 -m pip install 'polypack-mcp[polypack]'\n```\n\nFor one MCP client, use the default stdio server configuration. For Claude and\nCodex sharing the same durable memory, install once and create a long-running\nuser service:\n\n```sh\npolypack-mcp setup --store ~/.local/share/polypack-mcp\n```\n\nThis starts a stateless Streamable HTTP server at `http://127.0.0.1:8765/mcp/`, restarts it after a\nfailure, and prints client configuration snippets. The setup command uses\n`systemd --user`; on systems without systemd, start the server directly:\n\n```sh\npolypack-mcp --transport streamable-http --port 8765 --store ~/.local/share/polypack-mcp\n```\n\nIn shared Streamable HTTP mode, configure both clients with the URL. Do not configure them\nwith a `command` and `--store`, since that starts two processes competing for\nthe same durable store.\n\nCodex (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.polypack]\n  url = \"http://127.0.0.1:8765/mcp/\"\n```\n\nClaude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"polypack\": { \"url\": \"http://127.0.0.1:8765/mcp/\" }\n  }\n}\n```\n\n### Debian package\n\nThe Debian package installs and starts a system-level `polypack-mcp` service\nautomatically. It runs as the dedicated `polypack` user, stores data in\n`/var/lib/polypack-mcp`, and exposes the same local Streamable HTTP endpoint:\n\n```sh\nsudo apt install ./polypack-mcp_<version>_amd64.deb\n```\n\nAfter installation, point Claude and Codex at\n`http://127.0.0.1:8765/mcp/`. The default port can be changed in\n`/etc/default/polypack-mcp`, followed by a service restart. The service can be\nmanaged with:\n\n```sh\nsudo systemctl status polypack-mcp\nsudo systemctl restart polypack-mcp\n```\n\nThe PyPI installation remains user-managed and uses `polypack-mcp setup` to\ncreate a per-user service instead.\n\n### Optional semantic retrieval\n\nThe default installation uses Polypack's local graph, activation, and lexical\nretrieval without downloading an AI model. To enable local Qwen semantic\nretrieval, run:\n\n```sh\nsudo polypack-mcp embeddings setup qwen3 --system --store /var/lib/polypack-mcp\n```\n\nThis creates a managed localhost helper, downloads Qwen once into the store's\nembedding cache, and reindexes existing memories. The model is not bundled in\nthe Debian/RPM package.\n\nThe helper loads Qwen3-Embedding-0.6B in bfloat16 (~1GB resident once loaded,\nversus ~2.4GB in fp32) and unloads it after 15 minutes of inactivity,\nreloading automatically on the next request. `memory_recall` results include\na `semantic` entry in `scoreComponents` whenever the helper is reachable,\nalongside `lexical` and `activation` — the three sum to the reported `score`.\nIf the helper is stopped or errors, recall falls back to lexical + activation\nscoring automatically. Check or disable it with:\n\n```sh\npolypack-mcp embeddings status\nsudo polypack-mcp embeddings disable --system --store /var/lib/polypack-mcp\n```\n\nFor a PyPI user service, omit `sudo --system` and use the user store:\n\n```sh\npolypack-mcp embeddings setup qwen3\n```\n\n### APT repository\n\nThe latest Debian package is also published to the public APT repository at\n`https://imattau.github.io/polypack-mcp`. Configure it with the repository's\nsigning key, then install and update normally:\n\n```sh\ncurl -fsSL https://imattau.github.io/polypack-mcp/gpg.key \\\n  | sudo gpg --dearmor -o /usr/share/keyrings/polypack-mcp.gpg\necho \"deb [signed-by=/usr/share/keyrings/polypack-mcp.gpg] https://imattau.github.io/polypack-mcp stable main\" \\\n  | sudo tee /etc/apt/sources.list.d/polypack-mcp.list\nsudo apt update\nsudo apt install polypack-mcp\n```\n\nThe repository is updated automatically for each `v*.*.*` release tag. See\n`docs/apt-repository.md` for maintainer setup instructions.\n\n### RPM package\n\nRPM-based distributions can install from the public RPM repository:\n\n```sh\nsudo rpm --import https://imattau.github.io/polypack-mcp/rpm/RPM-GPG-KEY-polypack-mcp\nsudo tee /etc/yum.repos.d/polypack-mcp.repo >/dev/null <<'EOF'\n[polypack-mcp]\nname=Polypack MCP\nbaseurl=https://imattau.github.io/polypack-mcp/rpm/\nenabled=1\ngpgcheck=1\ngpgkey=https://imattau.github.io/polypack-mcp/rpm/RPM-GPG-KEY-polypack-mcp\nEOF\nsudo dnf install polypack-mcp\n```\n\nThe matching `.rpm` asset is also attached to the\n[GitHub release](https://github.com/imattau/polypack-mcp/releases):\n\n```sh\nsudo dnf install ./polypack-mcp-<version>-1.x86_64.rpm\n```\n\nThe RPM package provides the same systemd service, store location, localhost\nStreamable HTTP endpoint, and Python 3.12 requirement as the Debian package.\n\n## Run manually\n\n```sh\npip install -e '.[polypack]'\npolypack-mcp --store ./polypack-data\n```\n\nThe server exposes seventeen focused tools: `memory_store`, `memory_get`,\n`memory_update`, `memory_list_contexts`, `memory_delete`, `memory_recall`,\n`memory_context`, `memory_feedback`, `memory_suppress`, `memory_supersede`,\n`memory_consolidate`, `memory_link`, `memory_unlink`, `memory_thread`,\n`memory_store_batch`, `memory_link_batch`, and `graph_query`. It also publishes context,\nactive-memory, schema, stats, and agent workflow guidance resources under\n`polypack://`.\n\nMemory classes are `entity`, `episodic`, `procedural`, and `semantic`. Store\nproject or user preferences as `procedural` memories; `preference` is not a\nseparate memory class.\n\nWhen using a durable Polypack store, mutating operations checkpoint immediately\nand the server flushes the store during shutdown.\n\nRetrieval tools return `{items, metadata}`. Metadata includes candidate and\nexcluded counts, context matches, score components, fallback behavior, the\nretrieval version, and selection statistics. `memory_context` uses estimated\ntokens (`ceil(content characters / 4)`, minimum one) as its `token_budget`.\nAn item is never returned if it would exceed the remaining budget; budgets less\nthan or equal to zero are rejected. Context is a soft preference: matching\nmemories are preferred and unscoped global memories may be used as fallback.\nPass `strict_context: true` for isolation. An empty isolated result reports\n`reason: \"no_context_match\"` and the searched context.\n\n`memory_recall` can optionally hydrate related graph memories in the same call:\n\n```json\n{\n  \"query\": \"identity cache fix\",\n  \"context\": \"cross-agent\",\n  \"include_neighbors\": true,\n  \"edge_types\": [\"RESPONDS_TO\"],\n  \"depth\": 2,\n  \"neighbor_limit\": 3,\n  \"limit\": 20,\n  \"token_budget\": 4000\n}\n```\n\nNeighbor traversal is opt-in and bounded. `limit` caps the total response and\n`neighbor_limit` caps hydrated neighbors; metadata reports\n`moreNeighborsAvailable` when additional eligible neighbors were found. Neighbor\nitems include their distance and connecting relationship metadata. Use\n`memory_link` with the default\n`RESPONDS_TO` relationship for handoffs, reviews, and fixes that address an\nearlier memory. Graph edges are authoritative for relationships; use\n`graph_query(operation=\"relationship_diagnostics\")` to find legacy\n`provenance.responds_to` values that are not backed by edges. See\n`polypack://help/workflow` for the agent-facing workflow.\n\nFeedback is activation feedback: `useful=true` reinforces a memory and\n`useful=false` provides negative retrieval feedback. Responses expose activation\nbefore and after plus whether learned weights changed. Supersession and\nconsolidation materialize `SUPERSEDES`, `SUPERSEDED_BY`, and\n`CONSOLIDATED_FROM` graph edges.\n\nUse `memory_get` for exact ID lookup and `memory_update` for mutable fields\n(context, confidence, provenance, and metadata). Content changes should use\n`memory_supersede` so history remains intact. Use `memory_unlink` to correct a\nrelationship and `memory_list_contexts` to discover namespaces. `memory_delete`\nis permanent, requires `confirm=true`, and supports an optional revision check;\nprefer `memory_suppress` when retaining history is useful.\n\nPass `--store` to open a durable Polypack directory. Without it, the server uses\nthe in-memory reference backend, which is convenient for smoke tests.\nThe `polypack` extra requires `polypack-db>=3.3.1` and uses its native\n`ActivationEngine.working_memory` selector for context assembly.\n\n## Development\n\n```sh\npip install -e '.[dev]'\npytest\n```\n\nThe test suite includes an MCP client/server protocol smoke test covering tool\ndiscovery, memory storage, recall, and resource reads.\n\n## Documentation\n\n- [Getting started](docs/getting-started.md)\n- [Operations and configuration](docs/operations.md)\n- [Troubleshooting](docs/troubleshooting.md)\n",
  "bytes": 8940,
  "sha": "664d4fae820723693d1e9354849e9f47b1cfac69fa2939803654caa2a6373ac9",
  "repo_slug": "imattau/polypack-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_imattau_polypack_mcp_7783872c/readme"
}