{
  "markdown": "# PPM — Python Package Manager\n\n**pypm** packaging CLI with shared **PMLL** memory + Q-promise. Sibling: [drQedwards/pmll](https://github.com/drQedwards/pmll).\n\n![CI](https://img.shields.io/badge/build-passing-brightgreen)\n![License](https://img.shields.io/badge/license-MIT-blue)\n![Version](https://img.shields.io/badge/pypm-0.0.3--dev-yellow)\n[![npm](https://img.shields.io/npm/v/pmll-memory-mcp?label=pmll-memory-mcp)](https://www.npmjs.com/package/pmll-memory-mcp)\n[![Sponsor](https://img.shields.io/badge/sponsor-DrQedwards-ea4aaa?logo=github-sponsors)](https://github.com/sponsors/DrQedwards)\n\nLive Stellar `pmll-anchor` IDs: [docs/STELLAR.md](docs/STELLAR.md) · skills: [SKILL.md](SKILL.md) · promises: [Q_promise_lib/README.md](Q_promise_lib/README.md).\n\n> **TL;DR**: PPM packages Python (C CLI). Shared **PMLL** owns **memory/state** (`memory_silo_t`, exact `peek` + semantic `peek_semantic`,\n> SAT bridge, `init_pml`). Q-promise owns **temporal/control-flow** (`qpromise_*`, `libqpromise.so`)\n> — it does **not** replace the silo. Optional Stellar commitments hash off-chain\n> `CodeworkPayload`s into 32-byte digests via `pmll-anchor` (ABI: init/store/get/bump).\n> Companion packaging CLI + MCP memory server live in-tree.\n\nPMLL provides durable structured memory for agent workflows, alongside a PPM packaging CLI\n(hermetic bundles, plugins, signing) and the [PMLL Memory MCP server](#-pmll-memory-mcp-server).\nLong-term graph tools adapt [Context+](https://github.com/ForLoopCodes/contextplus).\n\n---\n\n## Table of Contents\n\n1. [Layers (post-merge)](#layers-post-merge)\n2. [Features](#-features)\n3. [Building from Source](#-building-from-source)\n4. [CLI Commands](#-cli-commands)\n5. [GPU & Security Features](#-gpu--security-features)\n6. [Plugin System](#-plugin-system)\n7. [Configuration](#-configuration)\n8. [PMLL Memory MCP Server](#-pmll-memory-mcp-server)\n9. [Stellar commitments](#-stellar-commitments-pmll-anchor)\n10. [Architecture](#-architecture)\n11. [Release Notes](#-release-notes)\n12. [Roadmap](#-roadmap)\n13. [Contributing & Sponsors](#-contributing--sponsors)\n\n---\n\n---\n\n## Layers (post-merge)\n\nTwo complementary layers — **not** substitutes for each other:\n\n| Layer | Owns | Key surface |\n|-------|------|-------------|\n| **PMLL** | Durable memory / state | `memory_silo_t`, `peek` / `peek_semantic`, `silo_set`, SAT bridge, `init_pml` |\n| **Q-promise** | Temporal / control-flow | `qpromise_*` API, `libqpromise.so`, deferred `qpromise_drain()` |\n\nQ-promise does **not** replace the silo. A promise may *reference* a memory key (and optional SAT state id); results are committed back with `silo_set` / `qpromise_resolve_commit`.\n\n### Intended loop\n\n```\nretrieve (peek / peek_semantic)\n  → compute / request work\n  → promise PENDING\n  → resolve / reject (optionally resolve_commit → silo)\n  → continuation (then / catch / finally via qpromise_drain)\n  → memory update\n  → retrieve again\n```\n\n**Thread safety:** the C Q-promise drain is **single-threaded**. Continuations run only during `qpromise_drain()` on the calling thread; callers must externally serialize access. Details: [`Q_promise_lib/README.md`](Q_promise_lib/README.md).\n\n### C core (PMLL)\n\nHeaders: `PMLL.h` · implementation: `PMLL.c`\n\n| Symbol | Role |\n|--------|------|\n| `memory_silo_t` | Associative/semantic silo: `tree`, `slots[]`, `embed_dim` (`PMLL_EMBED_DIM=32`), `slot_count` |\n| `silo_slot_t` | `key`, `content`, `embedding`, `resolved` |\n| `init_silo` / `free_silo` / `silo_set` | Allocate, free, write key/content + embedding |\n| `peek` | Exact key, else index |\n| `peek_semantic` | Cosine ≥ `min_sim` over embeddings (`silo_embed_text`, `silo_cosine_similarity`) |\n| `init_pml` | Sets every `assignment[i] = -1` (**undecided**) |\n| `check_conflict` | Treats `-1` as undecided (not sticky false from zero-fill) |\n| `sat_bridge_*` | Map 3SAT tokens → associative string literals in the silo |\n\n### Q-promise library\n\nBuild / test / API: **[`Q_promise_lib/README.md`](Q_promise_lib/README.md)** (authoritative). Public symbols are `qpromise_*`; shared object is `libqpromise.so`. The old prototype (`QMemNode` / `q_mem_*` / memory-chain walker) is removed; `Q_promises.h` is a compatibility include redirecting to `qpromise.h`.\n\n## ✨ Features\n\n| Command                    | What it does                                                                 |\n|----------------------------|------------------------------------------------------------------------------|\n| `pypm doctor`              | Checks Python headers, C compiler, OpenSSL, WASI toolchain, GPU, …          |\n| `pypm sandbox [-d DIR]`    | Drops you into an ephemeral temp dir (or custom DIR) with a full shell       |\n| `pypm plugin add NAME SRC` | Downloads a `.so` plugin (from URL or path) into `~/.pypm/plugins/`         |\n| `pypm plugin run NAME …`   | Executes `pypm_plugin_main()` inside the named plugin                        |\n| `pypm pypylock [-o FILE]`  | Bundles **every wheel + interpreter** into `dist/venv.tar.gz` (or FILE)     |\n| `pypm version`             | Prints the current CLI version                                               |\n| `ppm import PKG`           | Import and cache a package with GPU-accelerated hash verification            |\n| `ppm add PKG --lock`       | Add packages and update the lockfile                                         |\n| `ppm plan` / `ppm apply`   | Plan dependency changes, then apply them with an audit trail                 |\n| `ppm snapshot` / `ppm rollback` | Snapshot the environment; roll back to any prior state               |\n| `ppm sign` / `ppm verify`  | Sign artifacts (Ed25519) and verify cryptographic receipts                   |\n| `ppm sbom`                 | Generate a Software Bill of Materials (SBOM)                                 |\n\n*Road-mapped:* SAT dependency solver, parallel wheel cache, workspaces with single lockfile,\nWASM wheel resolution, Conda & Poetry import plugins.\n\n---\n\n## 🔧 Building from Source\n\n### System dependencies\n\n- C11 compiler (`gcc`, `clang`, or MSVC)\n- `libcurl` (plugin downloads)\n- `libdl` (dynamic loading — standard on Linux / macOS)\n- `tar` / `libarchive` (optional, for `pypylock` bundles)\n\n### Build & first run\n\n```bash\ngit clone https://github.com/drQedwards/PPM.git\ncd PPM\ncc -Wall -Wextra -ldl -lcurl -o pypm Ppm.c\n./pypm doctor        # Diagnose your dev box\n./pypm sandbox       # Spin up a throw-away REPL playground\n```\n\n### Q-promise shared library\n\n```bash\ncd Q_promise_lib\nmake clean && make test\nmake shared   # → libqpromise.so\n```\n\n### Optional: CUDA-accelerated build\n\n```bash\nnvcc -O3 CLI/CLI.cu -lcuda -o ppm-gpu\n./ppm-gpu import transformers torch --verbose\n```\n\n---\n\n## 🖥 CLI Commands\n\n### Import packages\n\n```bash\n# Import a single package\nppm import transformers\n\n# Import with a specific version\nppm import transformers==4.43.3\n\n# Import multiple packages\nppm import transformers torch numpy\n\n# Scan a Python file for imports and install them\nppm import --from-file my_script.py\n\n# Verbose — watch what's happening\nppm import transformers --verbose\n# 🔍 Resolving transformers...\n# ⬇️  Downloading transformers-4.43.3-py3-none-any.whl\n# 🔐 GPU integrity check: PASSED\n# ✅ transformers==4.43.3 imported successfully\n```\n\n### Project initialization\n\n```bash\nppm init\n# Creates:\n# .ppm/\n# ├── ledger.jsonl      ← append-only operation log\n# ├── state.json        ← current state\n# ├── lock.json         ← dependency lockfile\n# └── snapshots/        ← rollback points\n```\n\n### Dependency resolution & locking\n\n```bash\nppm add transformers torch==2.4.0 --lock\n\nppm plan\n# { \"plan\": \"install\", \"packages\": { \"transformers\": \"4.43.3\", ... } }\n\nppm apply --note \"Added ML stack\"\n```\n\n### Snapshot & rollback\n\n```bash\nppm snapshot --name \"before-upgrade\"\nppm snapshots\nppm rollback before-upgrade\n```\n\n### Environment diagnostics\n\n```bash\nppm doctor\n# ✅ Python dev headers found\n# ✅ C compiler available\n# ✅ CUDA toolkit available\n# 🏁 Diagnostics complete (0 issues found)\n```\n\n### Sandbox\n\n```bash\nppm sandbox                 # ephemeral temp directory\nppm sandbox -d /tmp/mydir   # custom directory\n```\n\n### Hermetic packaging\n\n```bash\nppm pypylock -o production-env.tar.gz\n```\n\n---\n\n## 🔐 GPU & Security Features\n\n### GPU-accelerated hash verification\n\n```bash\nppm import torch --verbose\n# 🚀 GPU hash verification: SHA-256 computed on device\n# ✅ Integrity verified: e3b0c44298fc1c149afbf4c8996fb924...\n```\n\n### GPU backend selection\n\n```bash\nppm ensure transformers --gpu auto    # auto-detect CUDA\nppm ensure transformers --gpu cu121  # force CUDA 12.1\nppm ensure transformers --gpu cpu    # CPU-only\n```\n\n### Ed25519 cryptographic signing\n\n```bash\nppm keygen --out-priv ed25519.priv --out-pub ed25519.pub\nppm sign   --sk ed25519.priv --file torch-2.4.0-*.whl --gpu ./libbreath_gpu.so\nppm verify --receipt torch-2.4.0-*.whl.receipt.json   --file torch-2.4.0-*.whl\n```\n\n### Provenance & SBOM\n\n```bash\nppm sbom        --out project-sbom.json\nppm provenance  --out provenance.json\nppm graph --dot | dot -Tpng -o deps.png\n```\n\n---\n\n## 🔌 Plugin System\n\n```bash\n# Install a plugin\nppm plugin add auditwheel https://cdn.example.com/auditwheel.so\n\n# Run it\nppm plugin run auditwheel repair --wheel torch-2.4.0-cp310-linux_x86_64.whl\n```\n\n### Writing a plugin (C)\n\n```c\n// hello.c\n#include <stdio.h>\nint pypm_plugin_main(int argc, char **argv) {\n    puts(\"Hello from a plugin 👋\");\n    return 0;\n}\n```\n\n```bash\ncc -shared -fPIC -o hello.so hello.c\nmv hello.so ~/.pypm/plugins/\npypm plugin run hello\n```\n\n---\n\n## ⚙️ Configuration\n\n### `pypm.toml`\n\n```toml\n[tool.ppm]\npython = \"^3.10\"\ndefault_gpu = \"auto\"\n\n[tool.ppm.backends]\ncpu.index   = \"https://download.pytorch.org/whl/cpu\"\ncu121.index = \"https://download.pytorch.org/whl/cu121\"\ncu122.index = \"https://download.pytorch.org/whl/cu122\"\n\ntorch_prefer        = \"2.4.*\"\ntransformers_prefer = \"4.43.*\"\n```\n\n### Environment variables\n\n```bash\nexport PYP_WORKSPACE_ROOT=/path/to/project   # override workspace detection\nexport PYP_DEBUG=1                           # enable debug output\nexport CUDA_VISIBLE_DEVICES=0               # control GPU usage\n```\n\n---\n\n## 🧠 PMLL Memory MCP Server\n\n> **Persistent memory logic loop with short-term KV context memory, Q-promise\n> deduplication, and [Context+](https://github.com/ForLoopCodes/contextplus) long-term\n> memory graph designed to improve context retention and retrieval for coding agents.**\n\n[![npm](https://img.shields.io/npm/v/pmll-memory-mcp?label=pmll-memory-mcp)](https://www.npmjs.com/package/pmll-memory-mcp)\n[![PyPI](https://img.shields.io/pypi/v/pmll-memory-mcp)](https://pypi.org/project/pmll-memory-mcp/)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry%20Submission-blue)](https://github.com/modelcontextprotocol/servers)\n\n`pmll-memory-mcp` is a **Model Context Protocol (MCP) server** with complementary\nshort-term KV and optional long-term graph layers. Server construction prefers\n`MCPServer` (mcp 2.x) and falls back to `FastMCP` (mcp 1.x) — see\n`mcp/pmll_memory_mcp/server.py`.\n\nGround tool names in code: TypeScript (`mcp/src/index.ts`) has 15 tools including\n`graphql` and names like `create_relation`; Python (`mcp/pmll_memory_mcp/server.py`)\nhas 14 tools (no `graphql`) with several longer names such as `create_memory_relation`.\nA ctypes demo in `Ppm-lib/pmll_mcp/` loads `libqpromise.so` via `qpromise_*`.\n\nMemory layers:\n\n- **Short-term KV cache** (5 tools) — session-isolated key-value memory with Q-promise deduplication, mirroring `PMLL.c::memory_silo_t`.\n- **Long-term memory graph** (6 tools) — adapted from [Context+](https://github.com/ForLoopCodes/contextplus) by [@ForLoopCodes](https://github.com/ForLoopCodes), providing a SQLite-backed property graph with typed nodes, weighted edges, temporal decay scoring (e^(-λt)), and semantic search via stable hashing embeddings.\n- **Solution engine** (3 tools) — bridges both layers with unified context resolution (short-term → long-term → miss), auto-promotion of frequently accessed entries, and unified memory status views.\n\nThe server is designed to be the **3rd initializer** alongside Playwright and other MCP tools — loaded once at the start of every agent task. Agents call `init` once at task start, then use `peek` before any expensive MCP tool invocation to avoid redundant calls. Frequently accessed entries are promoted to the long-term memory graph for semantic retrieval across sessions (SQLite-backed graph).\n\nTool counts differ by implementation (TS 15 incl. `graphql`; Python 14 — see note above). Historical docs below list the TypeScript tool surface.\n\n### Why it's a premium 3rd initializer\n\nModern Claude agent tasks routinely call Playwright, file-system tools, and other MCP servers.  Without a shared memory layer, every subtask re-initializes the same context from scratch.  `pmll-memory-mcp` eliminates this overhead with two complementary memory layers:\n\n```\nAgent task start\n  ├── 1st init: Playwright MCP\n  ├── 2nd init: Unstoppable Domains MCP  (see unstoppable-domains/)\n  └── 3rd init: pmll-memory-mcp   ← this server\n        ├── Short-term: all tool calls go through peek() first\n        └── Long-term: frequently accessed entries auto-promote to graph\n```\n\n### The `peek()` pattern\n\nBefore **every** expensive MCP tool invocation, agents call `peek` to check the cache:\n\n```typescript\n// Pseudocode — what the agent does automatically via MCP tool calls\n\n// 1. Check cache before navigating\nconst result = mcp.call(\"pmll-memory-mcp\", \"peek\", { session_id: sid, key: \"https://example.com\" });\nif (result.hit) {\n    const pageContent = result.value;          // ← served from PMLL silo, no browser needed\n} else {\n    // 2. Cache miss — do the real work\n    const pageContent = mcp.call(\"playwright\", \"navigate\", { url: \"https://example.com\" });\n    // 3. Populate the cache for future agents / subtasks\n    mcp.call(\"pmll-memory-mcp\", \"set\", {\n        session_id: sid,\n        key: \"https://example.com\",\n        value: pageContent,\n    });\n}\n```\n\n### Tools reference (15 tools)\n\n#### Short-term KV memory (5 tools)\n\n| Tool      | Input                                              | Output                                                      | Description                                       |\n|-----------|----------------------------------------------------|-------------------------------------------------------------|---------------------------------------------------|\n| `init`    | `session_id: str`, `silo_size: int = 256`          | `{status, session_id, silo_size}`                           | Set up PMLL silo + Q-promise state for session    |\n| `peek`    | `session_id: str`, `key: str`                      | `{hit, value?, index?}` or `{hit, status, promise_id}`      | Non-destructive cache + promise check             |\n| `set`     | `session_id: str`, `key: str`, `value: str`        | `{status: \"stored\", index}`                                 | Store KV pair in the silo                         |\n| `resolve` | `session_id: str`, `promise_id: str`               | `{status: \"resolved\"\\|\"pending\", payload?}`                 | Check/resolve a Q-promise continuation            |\n| `flush`   | `session_id: str`                                  | `{status: \"flushed\", cleared_count}`                        | Clear all silo slots at task completion           |\n\n#### GraphQL (1 tool)\n\n| Tool      | Input                                                         | Output                  | Description                                              |\n|-----------|---------------------------------------------------------------|-------------------------|----------------------------------------------------------|\n| `graphql` | `query: str`, `variables?: object`, `operationName?: str`     | `{data}` or `{errors}`  | Execute GraphQL queries/mutations against the memory store |\n\n#### Long-term memory graph (6 tools — adapted from [Context+](https://github.com/ForLoopCodes/contextplus))\n\nThese tools are adapted from [Context+](https://github.com/ForLoopCodes/contextplus) by [@ForLoopCodes](https://github.com/ForLoopCodes), providing SQLite-backed semantic memory with graph traversal, decay scoring, and cosine similarity search.\n\n| Tool                      | Input                                                           | Output                                                | Description                                                                        |\n|---------------------------|-----------------------------------------------------------------|-------------------------------------------------------|------------------------------------------------------------------------------------|\n| `upsert_memory_node`      | `session_id`, `type`, `label`, `content`, `metadata?`           | `{node}`                                              | Create or update a memory node with auto-generated TF-IDF embeddings               |\n| `create_relation`         | `session_id`, `source_id`, `target_id`, `relation`, `weight?`, `metadata?` | `{edge}`                                   | Create typed edges (relates_to, depends_on, implements, references, similar_to, contains) |\n| `search_memory_graph`     | `session_id`, `query`, `max_depth?`, `top_k?`, `edge_filter?`  | `{direct, neighbors, totalNodes, totalEdges}`         | Semantic search with graph traversal — direct matches + neighbor walk              |\n| `prune_stale_links`       | `session_id`, `threshold?`                                      | `{removed, remaining}`                                | Remove decayed edges (e^(-λt) below threshold) and orphan nodes with low access    |\n| `add_interlinked_context` | `session_id`, `items[]`, `auto_link?`                           | `{nodes, edges}`                                      | Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72 creates edges)          |\n| `retrieve_with_traversal` | `session_id`, `start_node_id`, `max_depth?`, `edge_filter?`    | `[{node, depth, pathRelations, relevanceScore}]`      | Walk outward from a node — returns reachable neighbors scored by decay & depth     |\n\n#### Solution engine (3 tools)\n\n| Tool                   | Input                                             | Output                                                 | Description                                                           |\n|------------------------|---------------------------------------------------|--------------------------------------------------------|-----------------------------------------------------------------------|\n| `resolve_context`      | `session_id`, `key`                               | `{source, value, score}`                               | Unified context lookup: short-term KV → long-term graph → miss        |\n| `promote_to_long_term` | `session_id`, `key`, `value`, `node_type?`, `metadata?` | `{promoted, nodeId}`                              | Promote a short-term KV entry to the long-term memory graph           |\n| `memory_status`        | `session_id`                                      | `{shortTerm, longTerm, promotionThreshold}`            | Unified view of short-term KV and long-term graph memory status       |\n\n### Installation\n\n#### Via `npx` (recommended — no install needed)\n\n```bash\nnpx pmll-memory-mcp\n```\n\n#### Via npm\n\n```bash\nnpm install -g pmll-memory-mcp\npmll-memory-mcp          # starts the stdio MCP server\n```\n\n#### Via pip (Python)\n\n```bash\npip install pmll-memory-mcp\npmll-memory-mcp          # starts the stdio MCP server\n```\n\n### Claude Desktop / MCP config (`claude_desktop_config.json`)\n\n#### NPX\n\n```json\n{\n  \"tools\": [\n    {\n      \"name\": \"init\",\n      \"description\": \"Set up PMLL silo and Q-promise state for a session. Call once at task start.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"silo_size\": { \"type\": \"integer\", \"default\": 256 }\n        },\n        \"required\": [\"session_id\"]\n      }\n    },\n    {\n      \"name\": \"peek\",\n      \"description\": \"Non-destructive cache lookup + Q-promise check. Call before every expensive MCP tool invocation.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"key\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\", \"key\"]\n      }\n    },\n    {\n      \"name\": \"set\",\n      \"description\": \"Store a key-value pair in the session silo. Call after a cache miss.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"key\": { \"type\": \"string\" },\n          \"value\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\", \"key\", \"value\"]\n      }\n    },\n    {\n      \"name\": \"resolve\",\n      \"description\": \"Check or resolve a Q-promise continuation by promise ID.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"promise_id\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\", \"promise_id\"]\n      }\n    },\n    {\n      \"name\": \"flush\",\n      \"description\": \"Clear all silo slots for a session. Call at task completion.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\"]\n      }\n    },\n    {\n      \"name\": \"graphql\",\n      \"description\": \"Execute GraphQL queries or mutations against the memory store.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"query\": { \"type\": \"string\" },\n          \"variables\": { \"type\": \"object\" },\n          \"operationName\": { \"type\": \"string\" }\n        },\n        \"required\": [\"query\"]\n      }\n    },\n    {\n      \"name\": \"upsert_memory_node\",\n      \"description\": \"Create or update a memory node with auto-generated TF-IDF embeddings.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"type\": { \"type\": \"string\" },\n          \"label\": { \"type\": \"string\" },\n          \"content\": { \"type\": \"string\" },\n          \"metadata\": { \"type\": \"object\" }\n        },\n        \"required\": [\"session_id\", \"type\", \"label\", \"content\"]\n      }\n    },\n    {\n      \"name\": \"create_relation\",\n      \"description\": \"Create a typed, weighted edge between two memory nodes.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"source_id\": { \"type\": \"string\" },\n          \"target_id\": { \"type\": \"string\" },\n          \"relation\": {\n            \"type\": \"string\",\n            \"enum\": [\"relates_to\", \"depends_on\", \"implements\", \"references\", \"similar_to\", \"contains\"]\n          },\n          \"weight\": { \"type\": \"number\" },\n          \"metadata\": { \"type\": \"object\" }\n        },\n        \"required\": [\"session_id\", \"source_id\", \"target_id\", \"relation\"]\n      }\n    },\n    {\n      \"name\": \"search_memory_graph\",\n      \"description\": \"Semantic search with graph traversal — returns direct matches and neighbor walk.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"query\": { \"type\": \"string\" },\n          \"max_depth\": { \"type\": \"integer\" },\n          \"top_k\": { \"type\": \"integer\" },\n          \"edge_filter\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\", \"query\"]\n      }\n    },\n    {\n      \"name\": \"prune_stale_links\",\n      \"description\": \"Remove decayed edges (e^(-λt) below threshold) and orphan nodes with low access count.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"threshold\": { \"type\": \"number\" }\n        },\n        \"required\": [\"session_id\"]\n      }\n    },\n    {\n      \"name\": \"add_interlinked_context\",\n      \"description\": \"Bulk-add nodes with auto-similarity linking (cosine >= 0.72 creates edges).\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"items\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"type\": { \"type\": \"string\" },\n                \"label\": { \"type\": \"string\" },\n                \"content\": { \"type\": \"string\" },\n                \"metadata\": { \"type\": \"object\" }\n              },\n              \"required\": [\"type\", \"label\", \"content\"]\n            }\n          },\n          \"auto_link\": { \"type\": \"boolean\" }\n        },\n        \"required\": [\"session_id\", \"items\"]\n      }\n    },\n    {\n      \"name\": \"retrieve_with_traversal\",\n      \"description\": \"Walk outward from a node, returning reachable neighbors scored by temporal decay and depth.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"start_node_id\": { \"type\": \"string\" },\n          \"max_depth\": { \"type\": \"integer\" },\n          \"edge_filter\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\", \"start_node_id\"]\n      }\n    },\n    {\n      \"name\": \"resolve_context\",\n      \"description\": \"Unified context lookup: short-term KV -> long-term graph -> miss. Returns source and score.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"key\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\", \"key\"]\n      }\n    },\n    {\n      \"name\": \"promote_to_long_term\",\n      \"description\": \"Promote a short-term KV entry to the long-term memory graph.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" },\n          \"key\": { \"type\": \"string\" },\n          \"value\": { \"type\": \"string\" },\n          \"node_type\": { \"type\": \"string\" },\n          \"metadata\": { \"type\": \"object\" }\n        },\n        \"required\": [\"session_id\", \"key\", \"value\"]\n      }\n    },\n    {\n      \"name\": \"memory_status\",\n      \"description\": \"Unified view of short-term KV and long-term graph memory status for a session.\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"session_id\": { \"type\": \"string\" }\n        },\n        \"required\": [\"session_id\"]\n      }\n    }\n  ]\n}\n\n```\n\n#### Docker\n\n```json\n{\n  \"mcpServers\": {\n    \"pmll-memory-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\",\n        \"-v\", \"pmll_data:/app/data\",\n        \"-e\", \"MEMORY_FILE_PATH=/app/data/memory.jsonl\",\n        \"--rm\", \"pmll-memory-mcp\"\n      ]\n    }\n  }\n}\n```\n\n### VS Code MCP configuration\n\nAdd to `.vscode/mcp.json` (or open **MCP: Open User Configuration** from the Command Palette):\n\n#### NPX\n\n```json\n{\n  \"servers\": {\n    \"pmll-memory-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"pmll-memory-mcp\"]\n    }\n  }\n}\n```\n\n#### Docker\n\n```json\n{\n  \"servers\": {\n    \"pmll-memory-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\",\n        \"-v\", \"pmll_data:/app/data\",\n        \"-e\", \"MEMORY_FILE_PATH=/app/data/memory.jsonl\",\n        \"--rm\", \"pmll-memory-mcp\"\n      ]\n    }\n  }\n}\n```\n\n### Docker\n\n```bash\n# Build from the repository root\ndocker build -f mcp/Dockerfile -t pmll-memory-mcp .\n\n# Run\ndocker run --rm -i pmll-memory-mcp:latest\n\n# Run with persistent KV memory via volume\ndocker run --rm -i \\\n  -v pmll_data:/app/data \\\n  -e MEMORY_FILE_PATH=/app/data/memory.jsonl \\\n  pmll-memory-mcp:latest\n```\n\n### Companion servers & integrations\n\n| Server / Integration | Directory / Source | Transport | Description |\n|--------|-----------|-----------|-------------|\n| **Unstoppable Domains** | [`unstoppable-domains/`](./unstoppable-domains/) | HTTP (remote) | Search, purchase, and manage Web3 domain names via natural conversation. |\n| **Context+** | [github.com/ForLoopCodes/contextplus](https://github.com/ForLoopCodes/contextplus) | Integrated | Long-term semantic memory graph, adapted into `memory-graph.ts` and `solution-engine.ts`. By [@ForLoopCodes](https://github.com/ForLoopCodes). |\n\nFull MCP server documentation: [`mcp/README.md`](mcp/README.md)\n\n---\n\n## ⚓ Stellar commitments (`pmll-anchor`)\n\nMemory / codework payloads stay **off-chain**. Optional **32-byte SHA-256 commitments** are **live on Stellar mainnet** via Soroban `pmll-anchor` (shared with [`drQedwards/pmll`](https://github.com/drQedwards/pmll)).\nABI unchanged: `init` / `store` / `get` / `bump` only — do not invent fields or contract IDs.\nThis PPM tree may **not** include the full `pmll-anchor/` contract sources; typed payload is still mirrored as [`skill.ts`](./skill.ts).\nInvoke docs / contract source: [pmll/SKILL.md](https://github.com/drQedwards/pmll/blob/main/SKILL.md). Local summary: [`SKILL.md`](./SKILL.md).\n\n| Network | Contract ID | Explorer |\n|---------|-------------|---------| \n| **mainnet** | `CCF3B64AXLS4OLY5RN4H4K2CFZAYNZCJQY5MKCKCVAKMZNH7G7F7XUUF` | [stellar.expert](https://stellar.expert/explorer/public/contract/CCF3B64AXLS4OLY5RN4H4K2CFZAYNZCJQY5MKCKCVAKMZNH7G7F7XUUF) |\n| testnet | `CDLQR24LLFWXTNGGJVJCRXAF3ZRDWFZRUFTDZ5SJOT2J33CS7DDYP7IU` | [stellar.expert](https://stellar.expert/explorer/testnet/contract/CDLQR24LLFWXTNGGJVJCRXAF3ZRDWFZRUFTDZ5SJOT2J33CS7DDYP7IU) |\n\nAdmin: `GBFOFCD3XDANQWSGMHKJJ2V3YXS2QQD7RNC4LMDBVNBTUJOQZ3RLSB3E` · wasm hash `1b6ad9c574e0f5c9e39968f836a410c03adcf057afa93a63d2710bd30fdd53ba`\n\nSkills summary: [`SKILL.md`](./SKILL.md) · full invoke docs: [pmll/SKILL.md](https://github.com/drQedwards/pmll/blob/main/SKILL.md)\n\n---\n\n## 🏛 Architecture\n\n```\n┌───────────────┐\n│ pypm (CLI)    │  ← C-based command parser\n└───────┬───────┘\n        │\n        ▼\n┌───────────────┐     ┌─────────────┐     ┌──────────────┐\n│ Workspace     │◀───▶│ Resolver    │◀───▶│ Wheel Cache  │\n│ (TOML / YAML) │     │ (SAT + PEP) │     │ (~/.cache)   │\n└───────────────┘     └─────┬───────┘     └─────┬────────┘\n                            │                   │\n                            ▼                   ▼\n                       ┌──────────┐       ┌────────────┐\n                       │ Env Mgr  │       │ Plugin Host│\n                       │ (.venv)  │       │ (dlopen)   │\n                       └──────────┘       └────────────┘\n\n┌─────────────────────────────────────────────────────┐\n│                  pmll-memory-mcp v1.0.1              │\n│                                                     │\n│  ┌──────────── Short-term (5 tools) ──────────┐    │\n│  │ index.ts → peekContext() → kv-store.ts      │    │\n│  │                  │                          │    │\n│  │                  └──────► q-promise-bridge   │    │\n│  └─────────────────────────────────────────────┘    │\n│                                                     │\n│  ┌──────── Long-term — Context+ (6 tools) ────┐    │\n│  │ memory-graph.ts → embeddings.ts             │    │\n│  │ (nodes, edges, decay, cosine similarity)    │    │\n│  └─────────────────────────────────────────────┘    │\n│                                                     │\n│  ┌──────── Solution Engine (3 tools) ─────────┐    │\n│  │ solution-engine.ts                          │    │\n│  │ (resolve_context, promote, memory_status)   │    │\n│  └─────────────────────────────────────────────┘    │\n└─────────────────────────────────────────────────────┘\n        │                    │\n        ▼                    ▼\n  PMLL.c / PMLL.h      Q_promise_lib/\n  (memory_silo_t)       (qpromise_* / libqpromise.so)\n```\n\n### Key components\n\n| File / Directory        | Purpose                                                          |\n|-------------------------|------------------------------------------------------------------|\n| `Ppm.c`                 | C-core CLI v0.0.3-dev — integrated single-file build (~500 LOC)  |\n| `Pypm.c`                | PyPM 0.3.x front-door dispatcher; delegates to module sources    |\n| `PMLL.c` / `PMLL.h`     | Associative/semantic silo, peek/peek_semantic, SAT bridge, init_pml=-1                |\n| `SAT.c` / `SAT.h`       | Boolean SAT solver used for dependency resolution                |\n| `Q_promise_lib/`        | Promise/continuation library (`qpromise_*`, `libqpromise.so`; single-threaded drain)  |\n| `skill.ts` / `SKILL.md` | Off-chain CodeworkPayload + Stellar skills entry                 |\n| `pmll-anchor/`          | Soroban commitment contract (source on pmll; may be absent here)                |\n| `lattice/`              | On pmll only — playable Stellar skills graph / ARC-AGI-3 play test              |\n| `mcp/`                  | TypeScript PMLL Memory MCP server (15 tools)                     |\n| `mcp/src/memory-graph.ts` | Long-term memory graph adapted from [Context+](https://github.com/ForLoopCodes/contextplus) |\n| `mcp/src/solution-engine.ts` | Solution engine bridging short-term KV + long-term graph    |\n| `mcp/src/embeddings.ts`  | TF-IDF embeddings and cosine similarity for semantic search     |\n| `CLI/`                  | Extended CLI interface                                           |\n| `Panda-lib/` `Torch-lib/` `Numpy-lib/` | Library integration shims                       |\n| `scripts/`              | Build helpers and automation scripts                             |\n\n---\n\n## 📝 Release Notes\n### Post-merge (2026-08) — semantic silo + Q-promise\n\n- PMLL C core: associative/semantic silo (`slots` + embeddings), `peek` + `peek_semantic`, SAT bridge, `init_pml` assignments start at `-1` (undecided).\n- Q-promise evolved to `qpromise_*` + `libqpromise.so`; prototype `QMemNode` / `q_mem_*` API removed.\n- Stellar skills / `skill.ts` aligned for off-chain `CodeworkPayload` hashing into existing `pmll-anchor` (ABI unchanged).\n- MCP servers prefer `MCPServer` with `FastMCP` fallback; Q-promise MCP demos load `libqpromise.so`.\n\n\n### pypm 0.0.3-dev (25 Jun 2025)\n\n**New & Improved**\n\n| Area                       | What's new                                                                         |\n|----------------------------|------------------------------------------------------------------------------------|\n| **Unified source**         | v0.0.1 + v0.0.2 merged into a single `pypm.c` file to simplify builds.            |\n| **Version bump**           | CLI now reports `0.0.3-dev`.                                                       |\n| **Workspace override**     | Honors `PYP_WORKSPACE_ROOT` and still climbs for `pypm-workspace.toml`.            |\n| **Doctor v2.1**            | Counts issues and exits with that count; inline Python probe via here-doc.         |\n| **Sandbox v2.1**           | `-d <DIR>` flag; default remains `mkdtemp`.                                        |\n| **Plugin fetcher hardening** | Creates `~/.pypm/plugins` safely; `CURLOPT_FAILONERROR` for HTTP 4xx/5xx; preserves plugin exit code. |\n| **Hermetic bundle flag**   | `pypylock -o <file>` works regardless of flag order; default `dist/venv.tar.gz`.   |\n| **Error surfacing**        | `fatal()` now shows `errno` via `perror`; `dlopen`/`curl` errors bubble up.        |\n\n**Fixes**\n- CLI flags after sub-commands were occasionally skipped by `getopt` → `optind = 2` before parsing.\n- Plugin loader returned success even when `dlsym` failed → now returns non-zero and closes handle.\n- Workspace scan no longer overwrites `cwd` for later `getcwd()` calls.\n\n**Breaking changes**\n1. `pypm version` is now a sub-command (not `--version` flag).\n2. `doctor` exit codes can now be >1 (numeric issue count).\n\n**Migration (0.0.2 → 0.0.3-dev)**\n\n| If you did …                         | Do this now                                          |\n|--------------------------------------|------------------------------------------------------|\n| `./pypm doctor && echo OK`           | Check `[[ $? -eq 0 ]]` or parse the numeric count.  |\n| Used `pypm_v002.c` / `pypm_v001.c`   | Switch to `pypm.c`, `make clean && make`.            |\n| Hard-coded `dist/venv.tar.gz` path   | Pass `-o` flag for custom output paths.              |\n\n**Known issues**\n- Windows build needs: `LoadLibraryW`, `_mktemp_s`, `bsdtar.exe` fallback (#22).\n- `pypylock` relies on shell `tar`; `libarchive` port planned for 0.0.4.\n- WASI/Rust/OpenSSL checks are informational stubs only.\n\n---\n\n### pmll-memory-mcp 1.0.1\n\n- **Version bump** — bumped from 1.0.0 to 1.0.1 to fix PyPI publishing (1.0.0 already existed on PyPI).\n- **Updated project descriptions** — PyPI and npm package descriptions now include \"in Claude Sonnet/Opus agent tasks\" to match the mcp/README.md tagline.\n- **README refresh** — PPM README.md MCP section updated with full tool reference, `peek()` pattern with TypeScript example, VS Code MCP configuration, and companion servers table from mcp/README.md.\n\n### pmll-memory-mcp 1.0.0\n\n- **Context+ integration** — 6 long-term memory graph tools adapted from\n  [Context+](https://github.com/ForLoopCodes/contextplus) by\n  [@ForLoopCodes](https://github.com/ForLoopCodes): `upsert_memory_node`,\n  `create_relation`, `search_memory_graph`, `prune_stale_links`,\n  `add_interlinked_context`, `retrieve_with_traversal`.\n- **Solution engine** — 2 new tools + 1 status tool bridging short-term KV cache\n  with long-term memory graph: `resolve_context`, `promote_to_long_term`,\n  `memory_status`.\n- **GraphQL tool** — `graphql` tool for flexible query/mutation access.\n- 15 total tools (5 short-term KV + 1 GraphQL + 6 long-term graph + 3 solution engine).\n- TF-IDF embeddings with cosine similarity search across the memory graph.\n- Temporal decay scoring (e^(-λt)) on graph edges with automatic pruning.\n- Auto-similarity linking (cosine ≥ 0.72) on bulk context additions.\n- Unified context resolution path: short-term → long-term → miss.\n\n### pmll-memory-mcp 0.2.0\n\n- Initial MCP Registry submission.\n- Five tools: `init`, `peek`, `set`, `resolve`, `flush`.\n- TypeScript KV store mirroring `PMLL.c::memory_silo_t`.\n- Q-promise registry (historical); current C API is `qpromise_*` / `libqpromise.so`.\n- Docker multi-stage image with persistent volume support.\n- Companion Unstoppable Domains MCP server included in `mcp/unstoppable-domains/`.\n\n---\n\n### pypm 0.0.2 (25 Jun 2025)\n\nWorkspace autodetect, Doctor v2, Sandbox upgrade, Plugin add/run, `pypylock -o`.\n**Breaking**: `--version` flag removed; `doctor` exits non-zero on issues.\n\n### pypm 0.0.1 (23 Jun 2025)\n\nInitial proof-of-concept — single-file CLI with `doctor`, `sandbox`, `plugin`, and `pypylock`.\n\n---\n\n## 🗺 Roadmap\n\n| Version | Planned features                                                           |\n|---------|----------------------------------------------------------------------------|\n| 0.0.4   | Lockfile parser + wheel copier for real hermetic bundles                   |\n| 0.0.5   | `libsolv`-backed dependency resolver                                        |\n| 0.1.0   | Cross-platform shims (Windows / macOS)                                     |\n| 0.1.1   | WASI toolchain detection & wheel preference                                |\n| future  | SAT dependency solver, parallel wheel cache, workspaces, WASM resolution   |\n\n---\n\n## 🤝 Contributing & Sponsors\n\nPull requests are welcome!  Open issues and PRs at  \n**<https://github.com/drQedwards/PPM/issues>**\n\nIf you find PPM or `pmll-memory-mcp` useful, please consider supporting development:\n\n[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-DrQedwards-ea4aaa?logo=github-sponsors&style=for-the-badge)](https://github.com/sponsors/DrQedwards)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-drqedwards-FFDD00?logo=buy-me-a-coffee&style=for-the-badge)](https://buymeacoffee.com/drqedwards)\n[![CoinGecko Portfolio](https://img.shields.io/badge/CoinGecko-Portfolio-8DC63F?logo=coingecko&style=for-the-badge)](https://www.coingecko.com/en/portfolios/public/jkdrq)\n\n---\n\n*Built by **Dr. Q Josef Kurk Edwards** — making Python packaging fast, deterministic, and hackable, with a shared PMLL memory stack.*\n",
  "bytes": 39849,
  "sha": "7603b13b89a5c596b2060fdf952e2cd938c939d60996f3b109dfad2827527b1a",
  "repo_slug": "drqedwards/ppm",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_drqedwards_pmll_memory_mcp_6829cc82/readme"
}