enigma-memory 0.1.3 → 0.1.4

package/docs/benchmark-reproducibility.md

@@ -4,7 +4,7 @@ This guide explains how to reproduce the current local Enigma memory benchmark,
 
 ## What is reproducible today
 
-The current package is `enigma-memory@0.1.3`. The local benchmark is available through the package script and the script file it wraps:
+The current package is `enigma-memory@0.1.4`. The local benchmark is available through the package script and the script file it wraps:
 
 ```sh
 cd enigma
@@ -19,7 +19,7 @@ The report schema is `enigma.memory_benchmark_suite.v1`. It is designed to be pu
 
 ## Reproduce and save JSON
 
-1. Use a clean checkout containing `enigma-memory@0.1.3`.
+1. Use a clean checkout containing `enigma-memory@0.1.4`.
 2. From a repository root that contains `enigma/package.json`, enter the package directory:
 
    ```sh
@@ -40,10 +40,12 @@ The report schema is `enigma.memory_benchmark_suite.v1`. It is designed to be pu
    npm run benchmark:memory-suite -- --out benchmark-report.json
    ```
 
-5. Preserve the JSON file with the command, package version, operating system/runtime, and review context that produced it.
+5. Preserve the JSON file with the command, package version, operating system/runtime, hardware class when relevant, and review context that produced it.
 6. When sharing the result publicly, share the generated JSON report only after confirming it still has `public_safe: true` and `schema: "enigma.memory_benchmark_suite.v1"`.
 
-The local fixture measures Enigma-controlled operations only: vault remember/update, vault export/import, passport context-pack retrieval, optimizer token estimates and duplicate removal, bundle/context-pack verification, abstention behavior, exact-answer recall over the deterministic fixture, and p50/p95 operation latency from `performance.now`.
+The local fixture measures Enigma-controlled operations only: vault remember/update, vault export/import, passport context-pack retrieval, deterministic local relevance filtering before optimizer tiering, optimizer token estimates and duplicate removal, bundle/context-pack verification, abstention behavior, exact-answer recall over the deterministic fixture, and p50/p95 operation latency from `performance.now`.
+
+Interpret improvements as local fixture behavior. Enigma reduces context-pack estimated prompt tokens by selecting the deterministic query/purpose/address-relevant local memories before optimizer tiering and deduplication; it does not measure provider invoice savings, token ROI, live model quality, or third-party memory superiority. Token estimates and p50/p95 timings can change across hardware, Node/runtime versions, script revisions, and fixture updates.
 
 ## Local baseline rows in the report
 
@@ -54,7 +56,7 @@ The report now includes `metrics.local_baseline_comparisons`, which compares det
 | `full_context` | Supplies every active fixture memory without optimization or deduplication. |
 | `recency_last_n` | Supplies the three most recently updated active fixture memories. |
 | `keyword_filter` | Supplies active fixture memories whose content or tags match deterministic query terms. |
-| `enigma_context_pack` | Uses the Enigma passport context-pack compiler and optimizer boundary. |
+| `enigma_context_pack` | Uses the Enigma passport context-pack compiler with deterministic local relevance filtering before optimizer tiering and deduplication. |
 
 The report also includes `public_claims_allowed`; keep public copy within those local-fixture boundaries unless separate reviewed external evidence exists.
 
@@ -71,7 +73,7 @@ The current local report mirrors some task categories from those benchmarks, but
 
 The current benchmark does not call external provider APIs, external SDKs, hosted memory services, ChatGPT native memory, Claude memory tooling, or third-party agent loops. Cross-provider rows in the report are profile labels that reuse the same Enigma context-pack boundary; they do not call or compare live provider models and are not live provider rankings.
 
-Real comparisons require fixed adapters, fixed datasets, fixed agent/tool loops, explicit provider terms review, and reviewed handling of secrets and raw benchmark data. Memory quality can change with the surrounding agent framework and tool loop, so a fair comparison must document more than the memory store.
+Real comparisons require fixed adapters, fixed datasets, fixed agent/tool loops, explicit provider terms review, and reviewed handling of secrets and raw benchmark data. Memory quality can change with the surrounding agent framework and tool loop, so a fair comparison must document more than the memory store. Until those inputs exist, external competitor rows stay requirements-only and must not carry recall, abstention, token, latency, or ranking scores.
 
 The current report must not be used as evidence of provider-side deletion, model forgetting, compliance certification, token ROI, provider invoice savings, benchmark leadership, hosted-cloud readiness, or “best in world” superiority.
 

package/docs/developer-ecosystem.md

@@ -25,7 +25,7 @@ The example app prints ids, counts, roots, and verification status only. It does
 
 ## CLI and CI loop
 
-The CI example installs Node 24, installs the published `enigma-memory@0.1.3` package, runs:
+The CI example installs Node 24, installs the published `enigma-memory@0.1.4` package, runs:
 
 ```sh
 npx enigma quickstart --overwrite

package/docs/memory-benchmarks.md

@@ -26,30 +26,34 @@ The harness measures local Enigma operations only:
 
 - vault remember/update operations;
 - vault export and import;
-- context-pack retrieval through the passport package;
-- optimizer plan token estimates and duplicate removal;
+- context-pack retrieval through the passport package, including deterministic local relevance filtering before optimizer tiering;
+- optimizer plan token estimates, tiering, and duplicate removal;
 - bundle and context-pack verification;
 - local baseline comparisons over the same deterministic fixture questions;
 - p50/p95 latency with `performance.now`.
 
 Reported metrics include exact-answer recall, abstention correctness, estimated prompt tokens, duplicate candidates removed where applicable, operation latency summaries, verification status, and same-boundary cross-provider profile rows.
 
+Enigma context-pack token improvements are achieved by local selection, not external-provider behavior: the passport compiler narrows active local memories to the deterministic query/purpose/address-relevant set before optimizer tiering and deduplication. This lowers estimated prompt tokens by excluding locally irrelevant fixture memories while preserving the same recall and abstention scoring boundary.
+
+Numeric token and latency values in generated reports are local fixture measurements. They can change with hardware, Node/runtime version, script version, and fixture contents, so copy should cite the command and report artifact rather than treating one run as a universal score.
+
 ## Local baseline comparison
 
-`metrics.local_baseline_comparisons` compares Enigma against deterministic local baselines only. Every row scores the same private fixture questions and keeps raw memory, question text, and answer text out of the report.
+`local_baseline_comparisons` (also mirrored at `metrics.local_baseline_comparisons`) compares Enigma against deterministic local baselines only. Every row scores the same private fixture questions and keeps raw memory, question text, and answer text out of the report.
 
 | Row | Boundary | Reported fields |
 | --- | --- | --- |
 | `full_context` | Supplies every active fixture memory without optimization or deduplication. | Recall, abstention correctness, estimated prompt tokens, selected memory count, p50/p95 local latency. |
 | `recency_last_n` | Supplies the three most recently updated active fixture memories. | Same fields; duplicate removal is marked not applicable. |
 | `keyword_filter` | Supplies active fixture memories whose content or tags match deterministic query terms. | Same fields; duplicate removal is marked not applicable. |
-| `enigma_context_pack` | Uses the Enigma passport context-pack compiler and optimizer boundary. | Same fields plus duplicate-removal counts from the Enigma optimizer plan. |
+| `enigma_context_pack` | Uses the Enigma passport context-pack compiler with deterministic local relevance filtering before optimizer tiering and deduplication. | Same fields plus duplicate-removal counts from the Enigma optimizer plan. |
 
 These rows are local package evidence only. They do not compare hosted providers, do not use provider APIs, and do not support invoice savings, ROI, compliance, model-forgetting, or benchmark-leadership claims.
 
 ## External competitor adapter requirements
 
-`external_competitor_adapters` is a requirements matrix, not a score table. Each row has `status: "not_run_requires_credentials_or_runtime"`, `can_run_in_this_harness: false`, `required_artifacts`, `official_doc`, an exact `boundary_reason`, and `scores_included: false`.
+`external_competitor_adapters` is a requirements matrix, not a score table. Each row has `status: "not_run_requires_credentials_or_runtime"`, `can_run_in_this_harness: false`, `required_artifacts`, `official_doc`, `official_positioning`, an exact `boundary_reason`, and `scores_included: false`.
 
 | Adapter | Official source | Required artifacts before scoring | Boundary reason |
 | --- | --- | --- | --- |
@@ -60,11 +64,13 @@ These rows are local package evidence only. They do not compare hosted providers
 | OpenAI ChatGPT native memory | https://help.openai.com/en/articles/8590148-memory-faq | ChatGPT account/runtime with native memory enabled; account-safe evaluation protocol; dataset prompts; evidence capture that excludes personal data and credentials. | ChatGPT native memory is a consumer-app feature rather than a public API surface available to this local package harness. |
 | Claude memory tool | https://support.anthropic.com/en/articles/11145838-using-claude-memory | Claude/provider runtime with the memory tool available; client-side tool configuration; fixed model/tool-use policy/prompts/dataset mapping; safe evidence capture. | The memory tool is provider/client-side and requires a Claude runtime plus tool environment that this benchmark does not control. |
 
-No external adapter row contains recall, abstention, token, latency, or ranking scores. Third-party claims stay blocked until the required credentials, runtimes, and datasets are supplied and reviewed.
+No external adapter row contains recall, abstention, token, latency, or ranking scores. Third-party rows remain requirements-only until the required credentials, runtimes, fixed agent/tool loops, and reviewed datasets are supplied and reviewed.
+
+The `official_positioning` field records only source-attributed context needed to build a future adapter: Letta/MemGPT runtime and SDK/API-key requirements; LangGraph short-term checkpointer and long-term namespaced store memory; Zep temporal Context Graph/Context Lake positioning and retrieval-latency claim; Mem0 platform/open-source memory stack; OpenAI native consumer-app memory; and Claude provider/client-side memory tooling. None of those facts are scored or verified by this local run.
 
 ## Claim limits
 
-The benchmark report is evidence for this local deterministic fixture only. It is not provider deletion proof, model forgetting proof, compliance certification, ROI evidence, provider invoice savings evidence, benchmark leadership proof, hosted cloud readiness, or a substitute for external LoCoMo/LongMemEval evaluation.
+The benchmark report is evidence for this local deterministic fixture only. Reported score improvements mean Enigma selected fewer locally irrelevant context-pack candidates under the same fixture questions; they are not provider deletion proof, model forgetting proof, compliance certification, ROI evidence, provider invoice savings evidence, benchmark leadership proof, hosted cloud readiness, or a substitute for external LoCoMo/LongMemEval evaluation.
 
 Cross-provider rows are profile labels using the same Enigma context-pack boundary. External competitor rows are adapter requirements only; they do not call, score, or rank live provider models.
 

package/docs/sdk-api.md

@@ -1,6 +1,6 @@
 # SDK and API guide
 
-This guide covers the public package imports for `enigma-memory@0.1.3`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
+This guide covers the public package imports for `enigma-memory@0.1.4`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
 
 ## Install and import style
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enigma-memory",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "Provider-agnostic AI memory passport and offline-verifiable proof layer.",
   "license": "Apache-2.0",

package/packages/mcp-server/src/index.js

@@ -17,7 +17,7 @@ import {
 const DEFAULT_BUNDLE = '.enigma/bundle.json';
 const JSONRPC_VERSION = '2.0';
 const MCP_PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.3' });
+const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.4' });
 const JSON_RPC_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 const JSON_RPC_ERROR = Object.freeze({
   INVALID_REQUEST: -32600,

package/packages/passport/src/index.js

@@ -36,6 +36,125 @@ const PUBLIC_PLAINTEXT_KEYS = new Set(['body', 'content', 'context', 'contexttex
 const SOURCE_REF_ROOT_RE = /^sha256:[a-f0-9]{64}$/;
 const PUBLIC_KEY_REQUIRED_FOR_CONTEXT_PACK_VERIFICATION = 'PUBLIC_KEY_REQUIRED_FOR_CONTEXT_PACK_VERIFICATION';
 
+const QUERY_RELEVANCE_STOPWORDS = new Set([
+  'about',
+  'after',
+  'again',
+  'against',
+  'also',
+  'and',
+  'any',
+  'are',
+  'assistant',
+  'because',
+  'been',
+  'before',
+  'being',
+  'between',
+  'can',
+  'could',
+  'current',
+  'does',
+  'from',
+  'has',
+  'have',
+  'how',
+  'into',
+  'its',
+  'latest',
+  'more',
+  'most',
+  'number',
+  'own',
+  'owns',
+  'please',
+  'should',
+  'that',
+  'the',
+  'their',
+  'then',
+  'there',
+  'these',
+  'they',
+  'this',
+  'use',
+  'using',
+  'was',
+  'what',
+  'when',
+  'where',
+  'which',
+  'who',
+  'whose',
+  'why',
+  'with',
+  'would',
+]);
+
+function addMeaningfulToken(tokens, token) {
+  if (token.length < 3) return;
+  if (!/[a-z]/u.test(token)) return;
+  if (QUERY_RELEVANCE_STOPWORDS.has(token)) return;
+  tokens.add(token);
+}
+
+function meaningfulTokensFrom(value) {
+  const tokens = new Set();
+  if (value === undefined || value === null) return tokens;
+  for (const match of String(value).toLowerCase().matchAll(/[a-z0-9]+(?:[-_][a-z0-9]+)*/gu)) {
+    const token = match[0];
+    addMeaningfulToken(tokens, token);
+    if (token.includes('-') || token.includes('_')) {
+      for (const part of token.split(/[-_]+/u)) addMeaningfulToken(tokens, part);
+    }
+  }
+  return tokens;
+}
+
+function addTokensFromValue(tokens, value) {
+  for (const token of meaningfulTokensFrom(value)) tokens.add(token);
+}
+
+function candidateRelevanceTokens(candidate) {
+  const tokens = new Set();
+  addTokensFromValue(tokens, candidate.content);
+  addTokensFromValue(tokens, candidate.metadata?.kind);
+  for (const tag of candidate.metadata?.purpose_tags ?? []) addTokensFromValue(tokens, tag);
+  return tokens;
+}
+
+function hasTokenOverlap(left, right) {
+  for (const token of left) {
+    if (right.has(token)) return true;
+  }
+  return false;
+}
+
+function strictQueryRelevance(args) {
+  return args.strict_relevance === true
+    || args.strictRelevance === true
+    || args.require_relevance === true
+    || args.requireRelevance === true
+    || args.query_relevance === 'strict'
+    || args.queryRelevance === 'strict';
+}
+
+function relevanceCandidateSet(args, candidates) {
+  if (args.queryAwareRelevance !== true) return candidates;
+  const query = typeof args.query === 'string' ? args.query.trim() : String(args.query ?? '').trim();
+  if (query.length === 0) return candidates;
+  const queryTokens = meaningfulTokensFrom(query);
+  if (queryTokens.size === 0) return candidates;
+
+  const relevant = [];
+  for (const candidate of candidates) {
+    if (hasTokenOverlap(queryTokens, candidateRelevanceTokens(candidate))) relevant.push(candidate);
+  }
+  if (relevant.length > 0) return relevant;
+  return strictQueryRelevance(args) ? [] : candidates;
+}
+
+
 function normalizedPublicKey(key) {
   return String(key).toLowerCase().replace(/[^a-z0-9]/g, '');
 }
@@ -215,8 +334,9 @@ function optimizedSelectionFrom(args, candidateAddresses, limit) {
     const candidate = optimizationCandidateFrom(args.vault, memoryAddr);
     if (candidate) candidates.push(candidate);
   }
+  const planCandidates = relevanceCandidateSet(args, candidates);
   const plan = createMemoryOptimizationPlan({
-    candidates,
+    candidates: planCandidates,
     prompt: args.query ?? '',
     pricing: contextPackPricing(args),
     now: args.now,
@@ -237,7 +357,7 @@ function optimizedSelectionFrom(args, candidateAddresses, limit) {
   }
   const selectedSet = new Set(selected);
   const selectedPlan = createMemoryOptimizationPlan({
-    candidates: candidates.filter((candidate) => selectedSet.has(candidate.address)),
+    candidates: planCandidates.filter((candidate) => selectedSet.has(candidate.address)),
     prompt: args.query ?? '',
     pricing: contextPackPricing(args),
     now: args.now,
@@ -503,11 +623,12 @@ export function compileContextPack(args = {}) {
   const tombstones = tombstoneAddressesFrom(vault);
   const limit = Number(args.limit ?? args.max_memories ?? args.maxMemories ?? 12);
   if (!Number.isInteger(limit) || limit < 0) throw new Error('compileContextPack limit must be a non-negative integer');
-  const candidateAddresses = requested ? [...requested] : [...active];
+  const hasExplicitMemoryAddresses = Boolean(requested);
+  const candidateAddresses = hasExplicitMemoryAddresses ? [...requested] : [...active];
   let selected = candidateAddresses.slice(0, limit);
   let optimizationPlan = null;
   if (optimizerEnabled(args)) {
-    const optimized = optimizedSelectionFrom({ ...args, vault }, candidateAddresses, limit);
+    const optimized = optimizedSelectionFrom({ ...args, vault, queryAwareRelevance: !hasExplicitMemoryAddresses }, candidateAddresses, limit);
     selected = optimized.selected;
     optimizationPlan = optimized.plan;
   }

package/scripts/build-installer-assets.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 
 export const INSTALLER_ASSET_SCHEMA = 'enigma.installer_assets.v1';
 export const INSTALLER_ASSET_PACKAGE = 'enigma-memory';
-export const INSTALLER_ASSET_VERSION = '0.1.3';
+export const INSTALLER_ASSET_VERSION = '0.1.4';
 export const INSTALLER_ASSET_GENERATED_AT = '1970-01-01T00:00:00.000Z';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);

package/scripts/run-memory-benchmarks.mjs

@@ -69,6 +69,7 @@ const EXTERNAL_COMPETITOR_ADAPTERS = Object.freeze([
       'Operator-supplied benchmark dataset or fixture mapping',
     ],
     official_doc: 'https://docs.letta.com/concepts/memgpt/',
+    official_positioning: 'Letta/MemGPT provides an agent memory runtime; this harness requires operator-supplied credentials/runtime and pinned SDK artifacts before any comparison.',
     can_run_in_this_harness: false,
     boundary_reason: 'This local harness has no Letta credentials, SDK installation, hosted/self-hosted Letta runtime, fixed agent loop, or approved external dataset, so no Letta score is produced.',
     scores_included: false,
@@ -84,6 +85,7 @@ const EXTERNAL_COMPETITOR_ADAPTERS = Object.freeze([
       'Fixed graph, model, tools, and dataset mapping',
     ],
     official_doc: 'https://docs.langchain.com/oss/python/langgraph/memory',
+    official_positioning: 'LangGraph memory includes short-term checkpointer memory and a long-term namespaced store; this harness does not execute that runtime.',
     can_run_in_this_harness: false,
     boundary_reason: 'This Node local package harness does not install or execute a LangGraph runtime, checkpointer, namespaced store, graph, model, or dataset adapter, so no LangGraph score is produced.',
     scores_included: false,
@@ -99,6 +101,7 @@ const EXTERNAL_COMPETITOR_ADAPTERS = Object.freeze([
       'Dataset ingestion and retrieval mapping',
     ],
     official_doc: 'https://help.getzep.com/',
+    official_positioning: 'Zep positions memory around a temporal Context Graph/Context Lake and sub-200ms retrieval; this harness does not verify that retrieval claim.',
     can_run_in_this_harness: false,
     boundary_reason: 'This local harness has no Zep credentials, client package, Context Graph or Context Lake runtime, ingestion job, or provider-approved retrieval dataset, so no Zep score or latency claim is produced.',
     scores_included: false,
@@ -114,6 +117,7 @@ const EXTERNAL_COMPETITOR_ADAPTERS = Object.freeze([
       'Dataset ingestion and scoring mapping',
     ],
     official_doc: 'https://docs.mem0.ai/',
+    official_positioning: 'Mem0 positions itself as a universal self-improving memory layer with platform and open-source stack options; this harness does not run either stack.',
     can_run_in_this_harness: false,
     boundary_reason: 'This local harness has no Mem0 credentials, SDK/runtime, configured extraction/retrieval loop, model/tool environment, or external dataset adapter, so no Mem0 score is produced.',
     scores_included: false,
@@ -129,6 +133,7 @@ const EXTERNAL_COMPETITOR_ADAPTERS = Object.freeze([
       'Evidence capture that excludes personal data and credentials',
     ],
     official_doc: 'https://help.openai.com/en/articles/8590148-memory-faq',
+    official_positioning: 'OpenAI ChatGPT native memory is a consumer-app/native capability and is not directly available through this local public-API harness.',
     can_run_in_this_harness: false,
     boundary_reason: 'ChatGPT native memory is a consumer-app feature rather than a public API surface available to this local package harness, so no OpenAI native-memory score is produced.',
     scores_included: false,
@@ -144,6 +149,7 @@ const EXTERNAL_COMPETITOR_ADAPTERS = Object.freeze([
       'Evidence capture that excludes personal data and credentials',
     ],
     official_doc: 'https://support.anthropic.com/en/articles/11145838-using-claude-memory',
+    official_positioning: 'Claude memory tooling is provider/client-side and requires a Claude runtime plus tool environment outside this local package harness.',
     can_run_in_this_harness: false,
     boundary_reason: 'The Claude memory tool is provider/client-side and requires a Claude runtime plus tool environment that this local package benchmark does not control, so no Claude memory-tool score is produced.',
     scores_included: false,
@@ -675,6 +681,7 @@ function compareLocalBaselines(vault, passport) {
 
     rows.push({
       id: baseline.id,
+      baseline: baseline.id,
       label: baseline.label,
       boundary: baseline.boundary,
       local_fixture_only: true,
@@ -684,6 +691,7 @@ function compareLocalBaselines(vault, passport) {
       exact_answer_questions: exactTotal,
       exact_answer_correct: exactCorrect,
       exact_answer_recall: exactTotal === 0 ? 0 : Number((exactCorrect / exactTotal).toFixed(6)),
+      recall: exactTotal === 0 ? 0 : Number((exactCorrect / exactTotal).toFixed(6)),
       abstention_questions: abstainTotal,
       abstention_correct: abstainCorrect,
       abstention_correctness: abstainTotal === 0 ? 0 : Number((abstainCorrect / abstainTotal).toFixed(6)),
@@ -740,6 +748,8 @@ function compareProviders(vault, passport, samples) {
       provider_runtime_observed: false,
       external_provider_called: false,
       same_enigma_context_pack_boundary: true,
+      scores_included: false,
+      not_external_competitor_score: true,
       boundary: {
         optimize: CONTEXT_BOUNDARY.optimize,
         max_estimated_tokens: CONTEXT_BOUNDARY.max_estimated_tokens,
@@ -863,6 +873,7 @@ export function runMemoryBenchmarkSuite(options = {}) {
         context_pack_verify_valid: contextVerification.valid === true,
       },
     },
+    local_baseline_comparisons: localBaselineRows,
     cross_provider_profiles: providerRows,
     external_competitor_adapters: EXTERNAL_COMPETITOR_ADAPTERS,
     public_claims_allowed: PUBLIC_CLAIMS_ALLOWED,