@drqedwards/pmll 2.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drQedwards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# pmll
+
+Persistent Memory Logic Loop MCP server. Short name for [pmll-memory-mcp](https://www.npmjs.com/package/pmll-memory-mcp).
+
+```bash
+npx pmll
+```
+
+Same tools as pmll-memory-mcp v2.0.4: peek KV cache, Q-promise dedup, Context+ long-term graph, solution engine.
+
+Combined Context+ + PMLL/peek benchmark (fastest config): 36ms TypeScript / 78ms Python.
+
+Repo: https://github.com/drQedwards/PPM and https://github.com/drQedwards/pmll
+
+## MCP config
+
+```json
+{
+  "mcpServers": {
+    "pmll": {
+      "command": "npx",
+      "args": ["-y", "pmll"]
+    }
+  }
+}
+```

package/agent_instructions.md

@@ -0,0 +1,123 @@
+# Context+ MCP - Agent Workflow
+
+## Purpose
+
+Context+ gives you structural awareness of the entire codebase without reading every file. These tools replace your default search and read operations — use them as your primary interface to the codebase.
+
+## PMLL Short-Term KV Memory (5 Tools)
+
+Before every expensive MCP tool invocation, agents MUST use the PMLL short-term KV memory tools to check the cache. This eliminates redundant calls and accelerates task execution. These tools are provided by the [`pmll-memory-mcp`](https://www.npmjs.com/package/pmll-memory-mcp) server (see [mcp/README.md](./README.md)).
+
+| Tool      | Input                                              | Description                                                |
+|-----------|----------------------------------------------------|------------------------------------------------------------|
+| `init`    | `session_id: str`, `silo_size: int = 256`          | Initialize a PMLL silo and Q-promise chain for the session |
+| `peek`    | `session_id: str`, `key: str`                      | Non-destructive cache lookup + Q-promise check (call before every expensive tool) |
+| `set`     | `session_id: str`, `key: str`, `value: str`        | Store a key-value pair in the silo after a cache miss      |
+| `resolve` | `session_id: str`, `promise_id: str`               | Check or resolve a Q-promise continuation                  |
+| `flush`   | `session_id: str`                                  | Clear all silo slots at task completion                    |
+
+### The `peek()` Pattern
+
+Call `peek` before every expensive tool invocation:
+
+1. **`init`** once at task start to set up the session silo
+2. **`peek`** before each expensive call — if hit, use the cached value; if pending, wait on the Q-promise
+3. **`set`** after a cache miss to populate the silo for future agents/subtasks
+4. **`resolve`** to check or fulfill Q-promise continuations
+5. **`flush`** at task end to clear all session slots
+
+This pattern ensures that Context+ tool results, Playwright page contents, and other expensive outputs are cached and reused across subtasks rather than re-fetched.
+
+## Tool Priority (Mandatory)
+
+You MUST use Context+ tools instead of native equivalents. Only fall back to native tools when a Context+ tool cannot fulfill the specific need.
+
+| Instead of…              | MUST use…                    | Why                                          |
+|--------------------------|------------------------------|----------------------------------------------|
+| `grep`, `rg`, `ripgrep`  | `semantic_code_search`       | Finds by meaning, not just string match      |
+| `find`, `ls`, `glob`     | `get_context_tree`           | Returns structure with symbols + line ranges |
+| `cat`, `head`, read file | `get_file_skeleton` first    | Signatures without wasting context on bodies |
+| manual symbol tracing    | `get_blast_radius`           | Traces all usages across the entire codebase |
+| keyword search           | `semantic_identifier_search` | Ranked definitions + call chains             |
+| directory browsing       | `semantic_navigate`          | Browse by meaning, not file paths            |
+
+## Workflow
+
+1. Start every task with `get_context_tree` or `get_file_skeleton` for structural overview
+2. Use `semantic_code_search` or `semantic_identifier_search` to find code by meaning
+3. Run `get_blast_radius` BEFORE modifying or deleting any symbol
+4. Prefer structural tools over full-file reads — only read full files when signatures are insufficient
+5. Run `run_static_analysis` after writing code
+6. Use `search_memory_graph` at task start for prior context, `upsert_memory_node` after completing work
+
+## Execution Rules
+
+- Think less, execute sooner: make the smallest safe change that can be validated quickly
+- Batch independent reads/searches in parallel — do not serialize them
+- If a command fails, diagnose once, pivot strategy, continue — cap retries to 1-2
+- Keep outputs concise: short status updates, no verbose reasoning
+
+## Tool Reference
+
+### PMLL Short-Term KV Memory
+
+| Tool      | When to Use                                                                  |
+|-----------|------------------------------------------------------------------------------|
+| `init`    | Once at task start. Set up the PMLL silo and Q-promise chain for the session.|
+| `peek`    | Before every expensive MCP tool call. Non-destructive cache + Q-promise check.|
+| `set`     | After a cache miss. Store the result so future agents/subtasks skip the call. |
+| `resolve` | When a Q-promise is pending. Check or fulfill the continuation.              |
+| `flush`   | At task end. Clear all silo slots for the session.                           |
+
+### GraphQL
+
+| Tool      | When to Use                                                                  |
+|-----------|------------------------------------------------------------------------------|
+| `graphql` | Execute GraphQL queries/mutations against the memory store with optional PMLL cache integration. |
+
+### Context+ Structural Tools
+
+| Tool                        | When to Use                                                  |
+|-----------------------------|--------------------------------------------------------------|
+| `get_context_tree`          | Start of every task. Map files + symbols with line ranges.   |
+| `get_file_skeleton`         | Before full reads. Get signatures + line ranges first.       |
+| `semantic_code_search`      | Find relevant files by concept.                              |
+| `semantic_identifier_search`| Find functions/classes/variables and their call chains.      |
+| `semantic_navigate`         | Browse codebase by meaning, not directory structure.         |
+| `get_blast_radius`          | Before deleting or modifying any symbol.                     |
+| `get_feature_hub`           | Browse feature graph hubs. Find orphaned files.              |
+| `run_static_analysis`       | After writing code. Catch errors deterministically.          |
+| `propose_commit`            | Validate and save file changes.                              |
+| `list_restore_points`       | See undo history.                                            |
+| `undo_change`               | Revert a change without touching git.                        |
+
+### Long-Term Memory Graph
+
+| Tool                        | When to Use                                                  |
+|-----------------------------|--------------------------------------------------------------|
+| `upsert_memory_node`        | Create/update memory nodes (concept, file, symbol, note).    |
+| `create_relation`           | Create typed edges between memory nodes.                     |
+| `search_memory_graph`       | Semantic search + graph traversal across neighbors.          |
+| `prune_stale_links`         | Remove decayed edges and orphan nodes.                       |
+| `add_interlinked_context`   | Bulk-add nodes with auto-similarity linking.                 |
+| `retrieve_with_traversal`   | Walk outward from a node, return scored neighbors.           |
+
+### Solution Engine
+
+| Tool                   | When to Use                                                           |
+|------------------------|-----------------------------------------------------------------------|
+| `resolve_context`      | Unified context lookup — checks short-term KV first, falls back to long-term semantic graph. |
+| `promote_to_long_term` | Promote a frequently-accessed short-term KV entry to the long-term memory graph. |
+| `memory_status`        | Get a unified view of both short-term (KV cache) and long-term (semantic graph) memory layers. |
+
+## Anti-Patterns
+
+1. Reading entire files without checking the skeleton first
+2. Deleting functions without checking blast radius
+3. Running independent commands sequentially when they can be parallelized
+4. Repeating failed commands without changing approach
+5. Calling expensive MCP tools without calling `peek` first to check the cache
+6. Forgetting to call `init` at task start or `flush` at task end, causing silent cache misses or stale data across sessions
+7. Storing frequently-accessed payloads only in short-term KV instead of promoting them to long-term memory with `promote_to_long_term`
+8. Calling `search_memory_graph` or `retrieve_with_traversal` directly instead of using `resolve_context`, which checks both memory layers in one call
+9. Ignoring Q-promise `pending` status from `peek` and re-issuing the same expensive call instead of waiting with `resolve`

package/benchmarks/benchmark_retrieval.md

@@ -0,0 +1,94 @@
+# Retrieval-quality benchmark harness (design)
+
+This document defines how we will measure **memory-graph retrieval quality**
+for `pmll_memory_mcp`. It is a unit-level retrieval bench — **not** an
+end-to-end agent-success scorecard.
+
+> **Accuracy (this harness)** = retrieval hit rate on labeled relevant nodes
+> (precision@k / recall@k / MRR over synthetic queries). It is **not** agent
+> task success, pass@k on coding tasks, or any product “X% accurate” claim.
+> Do not cite this stub (or a future full run of this harness alone) as
+> agent accuracy.
+
+Speed benches already live beside this file (`*-speed*.md`). This harness
+is the quality counterpart.
+
+Runnable stub: [`run_retrieval_stub.py`](./run_retrieval_stub.py).
+
+---
+
+## Required fields for any future accuracy claim
+
+Any published retrieval-quality number **must** record all of the following.
+Claims missing a field are incomplete.
+
+| Field | What to record |
+|-------|----------------|
+| **Dataset** | Synthetic coding-agent contexts: labeled `concept` / `file` / `symbol` / `note` nodes + edges. Version or hash of the seed set. |
+| **Task defs** | (1) retrieve relevant node(s) given a natural-language query; (2) promote KV → graph then retrieve; (3) restart durability (write → new process / reload → retrieve). |
+| **Baselines** | `no_graph` (empty / chance); `tfidf_legacy` if present; `hashing_only` (embed cosine, depth=0); `hashing+traversal` (embed + neighbor walk). Optional: vanilla KV peek / no memory. |
+| **n trials** | Number of labeled queries (and bootstrap resamples if CI reported). |
+| **Model / version** | **N/A** for pure retrieval unit bench (hashing embed + graph). Note separately if an agent E2E eval is attached — that is a different harness. |
+| **Prompts** | **N/A** for retrieval unit. Record **retrieval config**: `top_k`, decay (`DECAY_LAMBDA`), `max_depth`, similarity / stale thresholds. |
+| **Metrics** | `precision@k`, `recall@k`, `MRR` (mean reciprocal rank of first relevant hit). |
+| **Confidence intervals** | Method (e.g. bootstrap percentile over queries, or Wilson for binary hit@k) + level (e.g. 95%). |
+| **Comparison** | Same metrics vs vanilla KV peek / no-memory baseline on the same labeled queries. |
+| **“Accuracy” definition** | Exactly: fraction of queries where a labeled relevant node appears in the top-k retrieved set (hit rate), plus the ranked metrics above — **not** agent task success. |
+
+---
+
+## Dataset sketch
+
+Tiny seed (stub) and a future larger pack should share the same schema:
+
+```text
+node: {id_label, type, content, relevant_for: [query_ids...]}
+edge: {source_label, target_label, relation}
+query: {id, text, relevant_labels: [...], task: retrieve|promote_kv|restart}
+```
+
+Content themes: auth modules, config loaders, test helpers, API handlers —
+the kinds of fragments a coding agent would store across a session.
+
+---
+
+## Baselines & configs
+
+Default retrieval config for claims (override and record if changed):
+
+- `top_k=5`
+- `max_depth=0` (hashing-only) vs `max_depth=1..2` (hashing+traversal)
+- `DECAY_LAMBDA` / `SIMILARITY_THRESHOLD` as in `memory_graph.py`
+
+Baselines to report side-by-side on the same query set:
+
+1. **no_graph** — empty store (sanity: metrics ≈ 0)
+2. **hashing_only** — `search_graph(..., max_depth=0)`
+3. **hashing+traversal** — `search_graph(..., max_depth≥1)`
+4. **tfidf_legacy** — optional; only if a frozen TF-IDF path is exercised for comparison (not the production query path)
+5. **kv_peek / no_memory** — exact-key peek or empty memory (shows graph value-add)
+
+---
+
+## Metrics formulas
+
+For query \(q\) with relevant label set \(R_q\), retrieved top-\(k\) labels \(L_q\):
+
+- \(\mathrm{precision@}k = |L_q \cap R_q| / k\) (or `/|L_q|` if fewer than \(k\) returned — record which)
+- \(\mathrm{recall@}k = |L_q \cap R_q| / |R_q|\)
+- \(\mathrm{hit@}k = 1\) if \(L_q \cap R_q \neq \emptyset\), else \(0\)
+- \(\mathrm{MRR} = \mathrm{mean}_q\, 1/\mathrm{rank}\) of first relevant label (0 if none)
+
+Aggregate means over queries; report CI via the method declared above.
+
+---
+
+## Out of scope (separate harness)
+
+- Agent E2E task success, tool-choice quality, latency SLOs (see speed benches)
+- LLM judge scores, prompt ablations
+- Any “99%” / product accuracy marketing copy — **not derived from this file**
+
+When a full labeled pack lands, link results here and keep README claims
+tied to this harness definition — never invent a percentage without the
+table of required fields filled in.

package/benchmarks/contextplus-standalone-speed.md

@@ -0,0 +1,185 @@
+# Context+ MCP Tools — Standalone Speed Test Results
+
+> **Date**: 2026-04-04
+> **Environment**: Linux (GitHub Actions runner), Node.js 18+, Python 3.12.3
+> **Test runner**: Vitest 3.2.4 (TypeScript), pytest 9.0.2 (Python)
+> **Reference repos**: [ForLoopCodes/contextplus](https://github.com/ForLoopCodes/contextplus), [drQedwards/PPM](https://github.com/drQedwards/PPM)
+
+---
+
+## Overview
+
+This document benchmarks the **Context+ MCP tools in isolation** — the 6 long-term memory graph tools adapted from [Context+](https://github.com/ForLoopCodes/contextplus) — **without any `peek`/KV cache layer involved**. This shows how fast Context+'s graph operations are by themselves.
+
+The tools measured:
+- `upsert_memory_node` — create/update memory nodes with TF-IDF embeddings
+- `create_relation` — create typed edges between nodes
+- `search_memory_graph` — semantic search with graph traversal
+- `prune_stale_links` — remove decayed edges and orphan nodes
+- `add_interlinked_context` — bulk-add nodes with auto-similarity linking
+- `retrieve_with_traversal` — walk outward from a node, return scored neighbors
+
+Also benchmarks the underlying TF-IDF embedding engine (`tokenize`, `TfIdfVectorizer`, `cosineSimilarity`, `embed`).
+
+**No KV store. No peek. No short-term cache. Pure Context+ graph speed.**
+
+---
+
+## Test Suite
+
+| Suite | Framework | Tests | File |
+|-------|-----------|-------|------|
+| TypeScript | Vitest 3.2.4 | 27 | `__tests__/contextplus-speed.test.ts` |
+| Python | pytest 9.0.2 | 27 | `tests/test_contextplus_speed.py` |
+
+---
+
+## TypeScript Results (5 runs)
+
+### Overall Timing
+
+| Run | Total Duration | Transform | Collect | Tests | Prepare |
+|-----|---------------|-----------|---------|-------|---------|
+| 1   | 357ms         | 67ms      | 69ms    | 59ms  | 62ms    |
+| 2   | 347ms         | 64ms      | 67ms    | 59ms  | 69ms    |
+| 3   | 337ms         | 63ms      | 65ms    | 58ms  | 71ms    |
+| 4   | 344ms         | 63ms      | 63ms    | 58ms  | 57ms    |
+| 5   | 347ms         | 62ms      | 65ms    | 58ms  | 57ms    |
+
+**Average**: 346ms total, **58ms test execution** (27 tests)
+
+### Per-Test Breakdown (representative run)
+
+#### Embedding Engine (no peek, no KV)
+
+| Test | Time | What it measures |
+|------|------|-----------------|
+| tokenize: 100 strings | 2ms | Raw NLP tokenization throughput |
+| TfIdfVectorizer: build vocab from 50 docs | 2ms | Corpus vocabulary construction |
+| TfIdfVectorizer: vectorize 50 queries against 50-doc corpus | 3ms | Query vectorization throughput |
+| cosineSimilarity: 1000 vector comparisons | 1ms | Raw similarity computation |
+| embed: 100 documents through global vectorizer | 5ms | End-to-end embedding pipeline |
+
+#### `upsert_memory_node` (no peek, no KV)
+
+| Test | Time | Scale |
+|------|------|-------|
+| upsert 10 nodes (cold start) | 1ms | 10 nodes |
+| upsert 50 nodes | 2ms | 50 nodes |
+| upsert 100 nodes | 6–7ms | 100 nodes |
+| update existing nodes (50 upserts on 10 labels) | 1–2ms | 50 operations, 10 unique |
+| mixed node types (concept, file, symbol, note) | 1–2ms | 40 nodes, 4 types |
+
+#### `create_relation` (no peek, no KV)
+
+| Test | Time | Scale |
+|------|------|-------|
+| create 20 edges in a chain | 1–2ms | 21 nodes, 20 edges |
+| create edges with all 6 relation types | 1ms | 7 nodes, 6 edges |
+| create 45 edges in fully connected 10-node cluster | 1ms | 10 nodes, 45 edges |
+
+#### `search_memory_graph` (no peek, no KV)
+
+| Test | Time | Scale |
+|------|------|-------|
+| search empty graph | 1ms | 0 nodes |
+| search across 10 nodes | 1ms | 10 nodes |
+| search across 50 nodes | 2ms | 50 nodes |
+| search across 100 nodes with depth-2 traversal | 7–8ms | 100 nodes, 99 edges |
+| 10 successive searches on same graph | 1ms | 20 nodes, 10 queries |
+
+#### `prune_stale_links` (no peek, no KV)
+
+| Test | Time | Scale |
+|------|------|-------|
+| prune on graph with 50 fresh edges | 2ms | 51 nodes, 50 edges |
+| prune on empty graph | 0ms | 0 nodes |
+
+#### `add_interlinked_context` (no peek, no KV)
+
+| Test | Time | Scale |
+|------|------|-------|
+| bulk add 5 nodes with auto-linking | 1ms | 5 nodes |
+| bulk add 20 nodes with auto-linking | 3–9ms | 20 nodes + O(n²) similarity |
+| bulk add 10 nodes without auto-linking | 0ms | 10 nodes, no edges |
+
+#### `retrieve_with_traversal` (no peek, no KV)
+
+| Test | Time | Scale |
+|------|------|-------|
+| traverse depth-1 from root with 10 children | 0–1ms | 11 nodes returned |
+| traverse depth-2 from root through 3-level tree | 1ms | 26 nodes returned |
+| traverse with edge filter | 0ms | 2 nodes returned (filtered) |
+| traverse depth-3 chain of 30 nodes | 1ms | 4 nodes returned |
+
+---
+
+## Python Results (5 runs)
+
+| Run | Duration | Tests |
+|-----|----------|-------|
+| 1   | 0.06s    | 27    |
+| 2   | 0.06s    | 27    |
+| 3   | 0.06s    | 27    |
+| 4   | 0.06s    | 27    |
+| 5   | 0.06s    | 27    |
+
+**Average**: 60ms total (27 tests)
+
+---
+
+## Key Findings
+
+### Context+ is blazing fast on its own
+
+| Operation | Scale | Time | Per-op |
+|-----------|-------|------|--------|
+| `upsert_memory_node` | 100 nodes | 6–7ms | ~0.07ms/node |
+| `create_relation` | 45 edges (fully connected) | 1ms | ~0.02ms/edge |
+| `search_memory_graph` | 100 nodes + 99 edges, depth-2 | 7–8ms | Single query |
+| `search_memory_graph` | 20 nodes, 10 queries | 1ms | ~0.1ms/query |
+| `add_interlinked_context` | 20 nodes with auto-link | 3–9ms | Includes O(n²) similarity |
+| `retrieve_with_traversal` | 26-node tree, depth-2 | 1ms | Single traversal |
+| `prune_stale_links` | 51 nodes, 50 edges | 2ms | Full graph scan |
+| `embed` | 100 documents | 5ms | ~0.05ms/doc |
+| `cosineSimilarity` | 1000 comparisons | 1ms | ~0.001ms/comparison |
+
+### What this means
+
+1. **All 6 Context+ tools complete in single-digit milliseconds**, even at 100-node scale.
+2. **Semantic search across 100 nodes with depth-2 traversal takes only 7–8ms** — fast enough for real-time agent decision-making.
+3. **10 successive searches on a 20-node graph take 1ms total** — repeated queries are essentially free.
+4. **The TF-IDF embedding engine handles 100 documents in 5ms** — no external API latency.
+5. **1000 cosine similarity comparisons take 1ms** — vector math is negligible overhead.
+
+Context+ graph operations are already sub-millisecond per operation. When combined with PMLL's `peek()` caching (see [speed-test-results.md](./speed-test-results.md)), even these fast operations can be eliminated entirely for repeated lookups.
+
+---
+
+## How to Reproduce
+
+### TypeScript
+
+```bash
+cd mcp/
+npm install
+npx vitest run __tests__/contextplus-speed.test.ts --reporter=verbose
+```
+
+### Python
+
+```bash
+cd mcp/
+pip install pytest
+python3 -m pytest tests/test_contextplus_speed.py -v
+```
+
+### Benchmark loop (5 runs)
+
+```bash
+cd mcp/
+for i in 1 2 3 4 5; do
+  echo "--- Run $i ---"
+  npx vitest run __tests__/contextplus-speed.test.ts --reporter=verbose 2>&1 | grep -E '(✓|Duration)'
+done
+```