feat(memory): native short-term KV + dual-layer resolve_context

[drQedwards]

Summary for @forloopcodes

Core upgrade (not docs-only): native short-term KV + dual-layer resolve_context now ships inside Context+ TypeScript on this fork head (537b4db, via drQedwards/contextplus#7).

This is the implementable slice of what #28 / #30 documented and what closed #29 pitched with benchmarks — where integrate-memory upgrades in core, for further retrieval accuracy (labeled hit-rate) and lower redundant token burn via peek-before-expensive-tool.

Fork twin (merged): drQedwards#7

---

Why this matters vs prior landings

PR	What it did	Gap
#28	Memory & RAG docs for complementary pmll-memory-mcp	Docs only
#30	Document PMLL short-term KV in agent-instructions.md	Docs only — tools lived on complementary MCP
#29 (closed)	Heavier docs + speed tables	Never shipped native Context+ tools
This head	Ships init/peek/set/resolve/flush + resolve_context/promote_to_long_term/memory_status in Context+ MCP	Code + tests + docs

Agents were already instructed to peek before expensive calls and prefer resolve_context. Until this merge, those tools were not registered on the Context+ server itself (JSON long-term graph only).

---

What lands in core

New

• src/core/short-term-kv.ts — session silo, LRU silo_size, peek/set/flush + pending map for resolve
• src/core/solution-engine.ts — KV-first resolve_context, promote_to_long_term, memory_status
• test/main/short-term-kv.test.mjs
• Wiring in src/tools/memory-tools.ts + src/index.ts (MCP registration)

Tools shipped (MCP)

Tool	Role
init	Reset session silo (silo_size LRU)
peek	Two-stage guard: KV hit → pending → miss
set	Store key/value; evict LRU at capacity
resolve	Resolve pending promise / payload into KV
flush	Drop session store
resolve_context	Dual-layer: short-term KV first, then long-term graph
promote_to_long_term	Lift hot KV into persistent graph node
memory_status	Session + graph health snapshot

Also

• mergeRankHits helper in src/core/memory-graph.ts — unified ranking for dual-layer resolve_context (and search merge of direct+neighbor hits). This is not a searchGraph bugfix. Traversal ranking work that made depth-0 vs depth-1 metrics diverge lived on the complementary Python side (pmll#14 / harness stub), not as a Context+ graph-search defect.

---

Accuracy & speed claims (what we cite / what we do not)

PPM three-way only (avg test execution, illustrative of peek-before-expensive-tool):

Mode	~avg test exec
Baseline	~302ms
Context+-only	~63ms
Peek-only	~26ms
Combined	~36ms
Peek hits	~0ms

Retrieval quality = labeled P@k / R@k / MRR only. No 99% / 99.99% product-accuracy claims.

Do not treat supermodeltools “40%” (or similar marketing %) as evidence for this PR.

Complementary pmll-memory-mcp / PPM remains optional for Q-promise / Python SQLite P0 durability. No Python mcp/ dump into this repo.

---

Scope hygiene (historical noise on this long-lived fork main)

Older grab-bag commits on the fork head (UTM tracking on README backlinks, FUNDING.json, Obsidian-style tools hub under .contextplus/hubs/) are historical noise relative to the memory KV upgrade. Happy to split a focused PR (memory-only diff) if you prefer that over merging this main → main head as-is.

---

Tests

254 pass on dbc1ba5 (feat commit; merge tip 537b4db).

---

Test plan

• init → set → peek hit; miss / pending paths behave
• resolve_context prefers KV, falls through to graph, ranks via mergeRankHits
• promote_to_long_term writes a durable graph node from a silo key
• flush / silo LRU eviction at silo_size
• Existing memory-graph + new short-term-kv suites green (254)
• Skim docs: complementary MCP still optional; no Python dump; no inflated accuracy %
• Maintainer call: keep grab-bag UTM/FUNDING/tools-hub commits or ask for a focused re-cut

Thanks for maintaining Context+.

[vercel]

@drQedwards is attempting to deploy a commit to the ForLoopCodes' projects Team on Vercel.

A member of the Team first needs to authorize it.