Provides persistent key-value context memory and long-term graph memory to improve context retention and retrieval for AI coding agents.
Also known as drQedwards/PPM, ppm
- Stars
- 15
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Nov 8, 2026
- License
- MIT
What is PMLL Memory MCP?
PMLL Memory provides persistent key-value context memory and long-term graph memory to improve context retention and retrieval for AI coding agents. It exposes 5 tools, such as init, peek, set.
Summary generated from the project's README
About PMLL Memory MCP server
Improving context retention and retrieval for AI coding agents is the primary goal of this MCP server. It provides a dual-layer memory system that combines short-term key-value context with a long-term memory graph. Developers can use it to maintain session-isolated state through a short-term KV cache or build complex, persistent knowledge bases using a SQLite-backed property graph.
The server implements specific tools for managing these layers, including create_memory_relation for graph connections and semantic search capabilities. It utilizes a memory silo architecture to handle associative and semantic data, allowing agents to perform exact key lookups or cosine similarity searches via peek and peek_semantic functions. This setup is designed to work within the Model Context Protocol to bridge the gap between immediate task requirements and long-term project knowledge.
What you can do with it
- 1Maintain session-specific contextAn AI agent can store and retrieve temporary key-value pairs to keep track of immediate task progress.
- 2Manage temporal memory decayThe system can automatically score the relevance of old information using temporal decay.
Written from the project's README. Every use case is checked against a quote from it.
How to install PMLL Memory MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall PMLL Memory MCP in Claude Code
$ claude mcp add ppm -- npx -y pmll-memory-mcpInstall PMLL Memory MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ppm": {
"command": "npx",
"args": [
"-y",
"pmll-memory-mcp"
]
}
}
}Install PMLL Memory MCP in VS Code
.vscode/mcp.json
{
"servers": {
"ppm": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pmll-memory-mcp"
]
}
}
}Install PMLL Memory MCP in VS Code CLI
$ code --add-mcp '{"name":"ppm","type":"stdio","command":"npx","args":["-y","pmll-memory-mcp"]}'Install PMLL Memory MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ppm": {
"command": "npx",
"args": [
"-y",
"pmll-memory-mcp"
]
}
}
}Install PMLL Memory MCP in Codex
$ codex mcp add ppm -- npx -y pmll-memory-mcpInstall PMLL Memory MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.ppm] command = "npx" args = ["-y", "pmll-memory-mcp"]
Install PMLL Memory MCP in Gemini CLI
$ gemini mcp add -s user ppm npx -- -y pmll-memory-mcpInstall PMLL Memory MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ppm": {
"command": "npx",
"args": [
"-y",
"pmll-memory-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for pmll-memory-mcp 0.1.1 in an isolated container with no network and no keys. It answered and listed 5 tools.
PMLL Memory MCP tools 5
Read from the server with tools/listinitInitialise the PMLL memory silo for an agent session. Call this once at the start of every agent task, as the 3rd initializer alongside Playwright. Sets up the KV silo and prepares the Q-promise chain for the session.
peekNon-destructive context check — the core deduplication primitive. Call this before any Playwright or other MCP tool invocation to check whether the required context already exists in the PMLL silo or is in-flight as a Q-promise.
setStore a KV pair in the session's PMLL memory silo. Call after a successful (non-cached) MCP tool invocation to populate the silo so future `peek` calls return a cache hit. Mirrors PMLL.c::update_silo() writing a var/value pair into the silo.
resolveCheck or resolve a Q-promise continuation. Mirrors the `QThenCallback` mechanism in Q_promise_lib/Q_promises.h — the callback is invoked when a QMemNode's payload becomes available. If the promise is already resolved, returns its payload immediately. If still pending, returns `{status: "pending", payload: null}`.
flushClear all short-term KV slots for a session. Call at agent task completion to free memory. Mirrors the teardown of a memory_silo_t allocation (PMLL.c::free_pml).
| init | Initialise the PMLL memory silo for an agent session. Call this once at the start of every agent task, as the 3rd initializer alongside Playwright. Sets up the KV silo and prepares the Q-promise chain for the session. | |
| peek | Non-destructive context check — the core deduplication primitive. Call this before any Playwright or other MCP tool invocation to check whether the required context already exists in the PMLL silo or is in-flight as a Q-promise. | |
| set | Store a KV pair in the session's PMLL memory silo. Call after a successful (non-cached) MCP tool invocation to populate the silo so future `peek` calls return a cache hit. Mirrors PMLL.c::update_silo() writing a var/value pair into the silo. | |
| resolve | Check or resolve a Q-promise continuation. Mirrors the `QThenCallback` mechanism in Q_promise_lib/Q_promises.h — the callback is invoked when a QMemNode's payload becomes available. If the promise is already resolved, returns its payload immediately. If still pending, returns `{status: "pending", payload: null}`. | |
| flush | Clear all short-term KV slots for a session. Call at agent task completion to free memory. Mirrors the teardown of a memory_silo_t allocation (PMLL.c::free_pml). |
Configuration
CUDA_VISIBLE_DEVICESPYP_DEBUGPYP_WORKSPACE_ROOT
| Name | Description | |
|---|---|---|
| CUDA_VISIBLE_DEVICES | — | |
| PYP_DEBUG | — | |
| PYP_WORKSPACE_ROOT | — |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledrqedwards/ppm is public and reachablegithub.com/drqedwards/ppm ↗Pass
- Package names this repository as its sourcepmll-memory-mcp names drqedwards/ppm as sourcenpmjs.com/package/pmll-memory-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/drqedwards/ppm ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from pmll-memory-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPPM — Python Package Manager
pypm packaging CLI with shared PMLL memory + Q-promise. Sibling: drQedwards/pmll.
Live Stellar pmll-anchor IDs: docs/STELLAR.md · skills: SKILL.md · promises: Q_promise_lib/README.md.
TL;DR: PPM packages Python (C CLI). Shared PMLL owns memory/state (
memory_silo_t, exactpeek+ semanticpeek_semantic, SAT bridge,init_pml). Q-promise owns temporal/control-flow (qpromise_*,libqpromise.so) — it does not replace the silo. Optional Stellar commitments hash off-chainCodeworkPayloads into 32-byte digests viapmll-anchor(ABI: init/store/get/bump). Companion packaging CLI + MCP memory server live in-tree.
PMLL provides durable structured memory for agent workflows, alongside a PPM packaging CLI (hermetic bundles, plugins, signing) and the PMLL Memory MCP server. Long-term graph tools adapt Context+.
Table of Contents
- Layers (post-merge)
- Features
- Building from Source
- CLI Commands
- GPU & Security Features
- Plugin System
- Configuration
- PMLL Memory MCP Server
- Stellar commitments
- Architecture
- Release Notes
- Roadmap
- Contributing & Sponsors
Layers (post-merge)
Two complementary layers — not substitutes for each other:
| Layer | Owns | Key surface |
|---|---|---|
| PMLL | Durable memory / state | memory_silo_t, peek / peek_semantic, silo_set, SAT bridge, init_pml |
| Q-promise | Temporal / control-flow | qpromise_* API, libqpromise.so, deferred qpromise_drain() |
Q-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.
Intended loop
retrieve (peek / peek_semantic)
→ compute / request work
→ promise PENDING
→ resolve / reject (optionally resolve_commit → silo)
→ continuation (then / catch / finally via qpromise_drain)
→ memory update
→ retrieve again
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.
C core (PMLL)
Headers: PMLL.h · implementation: PMLL.c
| Symbol | Role |
|---|---|
memory_silo_t |
Associative/semantic silo: tree, slots[], embed_dim (PMLL_EMBED_DIM=32), slot_count |
silo_slot_t |
key, content, embedding, resolved |
init_silo / free_silo / silo_set |
Allocate, free, write key/content + embedding |
peek |
Exact key, else index |
peek_semantic |
Cosine ≥ min_sim over embeddings (silo_embed_text, silo_cosine_similarity) |
init_pml |
Sets every assignment[i] = -1 (undecided) |
check_conflict |
Treats -1 as undecided (not sticky false from zero-fill) |
sat_bridge_* |
Map 3SAT tokens → associative string literals in the silo |
Q-promise library
Build / test / API: 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.
✨ Features
| Command | What it does |
|---|---|
pypm doctor |
Checks Python headers, C compiler, OpenSSL, WASI toolchain, GPU, … |
pypm sandbox [-d DIR] |
Drops you into an ephemeral temp dir (or custom DIR) with a full shell |
pypm plugin add NAME SRC |
Downloads a .so plugin (from URL or path) into ~/.pypm/plugins/ |
pypm plugin run NAME … |
Executes pypm_plugin_main() inside the named plugin |
pypm pypylock [-o FILE] |
Bundles every wheel + interpreter into dist/venv.tar.gz (or FILE) |
pypm version |
Prints the current CLI version |
ppm import PKG |
Import and cache a package with GPU-accelerated hash verification |
ppm add PKG --lock |
Add packages and update the lockfile |
ppm plan / ppm apply |
Plan dependency changes, then apply them with an audit trail |
ppm snapshot / ppm rollback |
Snapshot the environment; roll back to any prior state |
ppm sign / ppm verify |
Sign artifacts (Ed25519) and verify cryptographic receipts |
ppm sbom |
Generate a Software Bill of Materials (SBOM) |
Road-mapped: SAT dependency solver (the standalone SAT.c CDCL solver exists but is not yet used for resolution), parallel wheel cache, workspaces with single lockfile,
WASM wheel resolution, Conda & Poetry import plugins.
🔧 Building from Source
System dependencies
- C11 compiler (
gcc,clang, or MSVC) libcurl(plugin downloads)libdl(dynamic loading — standard on Linux / macOS)tar/libarchive(optional, forpypylockbundles)
Build & first run
git clone https://github.com/drQedwards/PPM.git
cd PPM
cc -Wall -Wextra -ldl -lcurl -o pypm Ppm.c
./pypm doctor # Diagnose your dev box
./pypm sandbox # Spin up a throw-away REPL playground
Q-promise shared library
cd Q_promise_lib
make clean && make test
make shared # → libqpromise.so
cd ..
Optional: CUDA-accelerated build
nvcc -O3 CLI/CLI.cu -lcuda -o ppm-gpu
./ppm-gpu import transformers torch --verbose
🖥 CLI Commands
Import packages
# Import a single package
ppm import transformers
# Import with a specific version
ppm import transformers==4.43.3
# Import multiple packages
ppm import transformers torch numpy
# Scan a Python file for imports and install them
ppm import --from-file my_script.py
# Verbose — watch what's happening
ppm import transformers --verbose
# 🔍 Resolving transformers...
# ⬇️ Downloading transformers-4.43.3-py3-none-any.whl
# 🔐 GPU integrity check: PASSED
# ✅ transformers==4.43.3 imported successfully
Project initialization
ppm init
# Creates:
# .ppm/
# ├── ledger.jsonl ← append-only operation log
# ├── state.json ← current state
# ├── lock.json ← dependency lockfile
# └── snapshots/ ← rollback points
Dependency resolution & locking
ppm add transformers torch==2.4.0 --lock
ppm plan
# { "plan": "install", "packages": { "transformers": "4.43.3", ... } }
ppm apply --note "Added ML stack"
Snapshot & rollback
ppm snapshot --name "before-upgrade"
ppm snapshots
ppm rollback before-upgrade
Environment diagnostics
ppm doctor
# ✅ Python dev headers found
# ✅ C compiler available
# ✅ CUDA toolkit available
# 🏁 Diagnostics complete (0 issues found)
Sandbox
ppm sandbox # ephemeral temp directory
ppm sandbox -d /tmp/mydir # custom directory
Hermetic packaging
ppm pypylock -o production-env.tar.gz
🔐 GPU & Security Features
GPU-accelerated hash verification
ppm import torch --verbose
# 🚀 GPU hash verification: SHA-256 computed on device
# ✅ Integrity verified: e3b0c44298fc1c149afbf4c8996fb924...
GPU backend selection
ppm ensure transformers --gpu auto # auto-detect CUDA
ppm ensure transformers --gpu cu121 # force CUDA 12.1
ppm ensure transformers --gpu cpu # CPU-only
Ed25519 cryptographic signing
ppm keygen --out-priv ed25519.priv --out-pub ed25519.pub
ppm sign --sk ed25519.priv --file torch-2.4.0-*.whl --gpu ./libbreath_gpu.so
ppm verify --receipt torch-2.4.0-*.whl.receipt.json --file torch-2.4.0-*.whl
Provenance & SBOM
ppm sbom --out project-sbom.json
ppm provenance --out provenance.json
ppm graph --dot | dot -Tpng -o deps.png
🔌 Plugin System
# Install a plugin
ppm plugin add auditwheel https://cdn.example.com/auditwheel.so
# Run it
ppm plugin run auditwheel repair --wheel torch-2.4.0-cp310-linux_x86_64.whl
Writing a plugin (C)
// hello.c
#include <stdio.h>
int pypm_plugin_main(int argc, char **argv) {
puts("Hello from a plugin 👋");
return 0;
}
cc -shared -fPIC -o hello.so hello.c
mv hello.so ~/.pypm/plugins/
pypm plugin run hello
⚙️ Configuration
pypm.toml
[tool.ppm]
python = "^3.10"
default_gpu = "auto"
[tool.ppm.backends]
cpu.index = "https://download.pytorch.org/whl/cpu"
cu121.index = "https://download.pytorch.org/whl/cu121"
cu122.index = "https://download.pytorch.org/whl/cu122"
torch_prefer = "2.4.*"
transformers_prefer = "4.43.*"
Environment variables
export PYP_WORKSPACE_ROOT=/path/to/project # override workspace detection
export PYP_DEBUG=1 # enable debug output
export CUDA_VISIBLE_DEVICES=0 # control GPU usage
🧠 PMLL Memory MCP Server
Persistent memory logic loop with short-term KV context memory, Q-promise deduplication, and Context+ long-term memory graph designed to improve context retention and retrieval for coding agents.
pmll-memory-mcp is a Model Context Protocol (MCP) server with complementary
short-term KV and optional long-term graph layers. Server construction prefers
MCPServer (mcp 2.x) and falls back to FastMCP (mcp 1.x) — see
mcp/pmll_memory_mcp/server.py.
Ground tool names in code: TypeScript (mcp/src/index.ts) has 15 tools including
graphql and names like create_relation; Python (mcp/pmll_memory_mcp/server.py)
has 14 tools (no graphql) with several longer names such as create_memory_relation.
A ctypes demo in Ppm-lib/pmll_mcp/ loads libqpromise.so via qpromise_*.
Memory layers:
- Short-term KV cache (5 tools) — session-isolated key-value memory with Q-promise deduplication, mirroring
PMLL.c::memory_silo_t. - Long-term memory graph (6 tools) — adapted from Context+ by @ForLoopCodes, providing a SQLite-backed property graph with typed nodes, weighted edges, temporal decay scoring (e^(-λt)), and semantic search via stable hashing embeddings.
- 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.
The 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).
Tool counts differ by implementation (TS 15 incl. graphql; Python 14 — see note above). Historical docs below list the TypeScript tool surface.
Why it's a premium 3rd initializer
Modern 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:
Agent task start
├── 1st init: Playwright MCP
├── 2nd init: Unstoppable Domains MCP (see unstoppable-domains/)
└── 3rd init: pmll-memory-mcp ← this server
├── Short-term: all tool calls go through peek() first
└── Long-term: frequently accessed entries auto-promote to graph
The peek() pattern
Before every expensive MCP tool invocation, agents call peek to check the cache:
// Pseudocode — what the agent does automatically via MCP tool calls
// 1. Check cache before navigating
const result = mcp.call("pmll-memory-mcp", "peek", { session_id: sid, key: "https://example.com" });
if (result.hit) {
const pageContent = result.value; // ← served from PMLL silo, no browser needed
} else {
// 2. Cache miss — do the real work
const pageContent = mcp.call("playwright", "navigate", { url: "https://example.com" });
// 3. Populate the cache for future agents / subtasks
mcp.call("pmll-memory-mcp", "set", {
session_id: sid,
key: "https://example.com",
value: pageContent,
});
}
Tools reference (15 tools)
Short-term KV memory (5 tools)
| Tool | Input | Output | Description |
|---|---|---|---|
init |
session_id: str, silo_size: int = 256 |
{status, session_id, silo_size, cleared} |
Set up or reset the session silo + Q-promise state (cleared is always true) |
peek |
session_id: str, key: str |
{hit, value?, index?} or {hit, status, promise_id} |
Non-destructive cache + promise check |
set |
session_id: str, key: str, value: str |
{status: "stored", index} |
Store KV pair in the silo |
resolve |
session_id: str, promise_id: str |
{status: "resolved"|"pending", payload?} |
Check/resolve a Q-promise continuation |
flush |
session_id: str |
{status: "flushed", cleared_count} |
Clear all silo slots at task completion |
GraphQL (1 tool)
| Tool | Input | Output | Description |
|---|---|---|---|
graphql |
query: str, variables?: object, operationName?: str |
{data} or {errors} |
Execute GraphQL queries/mutations against the memory store |
Long-term memory graph (6 tools — adapted from Context+)
These tools are adapted from Context+ by @ForLoopCodes, providing SQLite-backed semantic memory with graph traversal, decay scoring, and cosine similarity search.
| Tool | Input | Output | Description |
|---|---|---|---|
upsert_memory_node |
session_id, type, label, content, metadata? |
{node} |
Create or update a memory node with auto-generated stable hashing embeddings |
create_relation |
session_id, source_id, target_id, relation, weight?, metadata? |
{edge} |
Create typed edges (relates_to, depends_on, implements, references, similar_to, contains) |
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 |
prune_stale_links |
session_id, threshold? |
{removed, remaining} |
Remove decayed edges (e^(-λt) below threshold) and orphan nodes with low access |
add_interlinked_context |
session_id, items[], auto_link? |
{nodes, edges} |
Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72 creates edges) |
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 |
Solution engine (3 tools)
| Tool | Input | Output | Description |
|---|---|---|---|
resolve_context |
session_id, key |
{source, value, score} |
Unified context lookup: short-term KV → long-term graph → miss |
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 |
memory_status |
session_id |
{shortTerm, longTerm, promotionThreshold} |
Unified view of short-term KV and long-term graph memory status |
Installation
Via npx (recommended — no install needed)
npx pmll-memory-mcp
Via npm
npm install -g pmll-memory-mcp
pmll-memory-mcp # starts the stdio MCP server
Via pip (Python)
pip install pmll-memory-mcp
pmll-memory-mcp # starts the stdio MCP server
Claude Desktop / MCP config (claude_desktop_config.json)
PMLL Memory MCP questions
How do I add PMLL Memory MCP to Claude Code?
Run claude mcp add ppm -- npx -y pmll-memory-mcp in your terminal. Add --scope user to make it available in every project.
How do I add PMLL Memory MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does PMLL Memory MCP provide?
It exposes 5 tools, including init, peek, set, resolve, flush.
What are the memory layers in PMLL Memory MCP?
It features a short-term KV cache for session-isolated memory and a long-term memory graph using a SQLite-backed property graph.
Does the server support semantic search?
Yes, the long-term memory graph provides semantic search via stable hashing embeddings.
What is the purpose of the solution engine?
The solution engine bridges the short-term KV cache and long-term memory graph layers with unified context resolution.