jamgate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jam
+
+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,229 @@
+# Jamgate
+
+[![CI](https://github.com/amirj4m/jamgate/actions/workflows/ci.yml/badge.svg)](https://github.com/amirj4m/jamgate/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/jamgate.svg)](https://www.npmjs.com/package/jamgate)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+> A neutral memory quality-gate for AI agents — **a gate, not a store.** One shared
+> memory of you — who you are, how you're doing, what you're working on — that every AI
+> agent reads from and writes to, kept honest at write time. Local-first, no cloud calls,
+> one dependency.
+
+```bash
+claude mcp add jamgate -- npx jamgate
+```
+
+## The problem: memory quality, not storage
+
+You are one person, but every AI you use is a separate island. You design with one,
+research with another, code with a third — and none of them know what the others know,
+so you re-explain "what I'm working on" every time.
+
+The tools that try to fix this mostly **store everything**, so shared memory bloats with
+junk: one production audit of a leading memory system found **97.8% of its stored entries
+were junk** ([source](https://github.com/mem0ai/mem0/issues/4573)) — duplicates, trivia,
+one-off chatter, stale states. Sharing memory is the easy part. Keeping the shared memory
+*clean and current* is the unsolved part.
+
+Jamgate sits in the **write path** and decides what deserves to be remembered, before it
+is stored:
+
+```
+                 without a gate                          with Jamgate
+   ┌──────────────────────────────────┐   ┌──────────────────────────────────────┐
+   │ "remember I'm on a call"          │   │ ✗ rejected — not durable             │
+   │ "I use Windows"  ← from 6mo ago   │   │ ⇄ superseded — "I use Linux" wins    │
+   │ "I use Windows"  (again)          │   │ ✗ duplicate — already known          │
+   │ "I use Linux"                     │   │ ✓ saved — durable, changes answers   │
+   │ "my name is Sam" (agent guessed)  │   │ ⚠ conflict — lower trust, ask first  │
+   └──────────────────────────────────┘   └──────────────────────────────────────┘
+     everything piles up, 98% junk           small, current, trustworthy
+```
+
+## The idea
+
+**Jamgate is one shared memory of you that every agent plugs into — kept honest by a
+quality gate.** It runs as an [MCP](https://modelcontextprotocol.io) server, so any
+MCP-capable agent (Claude Code, Claude Desktop, Cursor, …) connects to the *same* memory
+on your machine. Because it filters at write time, that memory stays small, accurate, and
+contradiction-free instead of bloating with junk.
+
+```
+Agent → [ Jamgate quality gate ] → local store (~/.jamgate/memory.json)
+        save_memory / recall_memory / forget_memory
+```
+
+## What it does — the gate layers
+
+A memory is kept only if it is **durable** (still true after this session) and would
+**change a future answer**. The gate is a hybrid pipeline, cheapest checks first:
+
+| Layer | What it does |
+| --- | --- |
+| **Rule pre-filter** | Drops obvious non-durable noise ("I'm on a call now") before it reaches the store. |
+| **Agent salience** | Uses the calling agent's own understanding as the main "is this worth remembering?" filter — no extra LLM call of our own. |
+| **Exact dedup** | Identical facts are never stored twice. |
+| **Time-aware supersession** | Every memory is a timestamped event; a newer fact retires an older one on the same `subject` by recency — no contradiction pile-up, and it never throws your own stale words back at you. |
+| **Trust hierarchy** | A lower-trust source (an agent's guess) can't silently overwrite a higher-trust fact (something you said explicitly). The gate refers the conflict back to you instead. |
+| **Semantic near-dup** *(optional)* | With local embeddings on, a save that *means* the same as an existing memory returns as a `possible_duplicate` to confirm, rather than piling up. |
+| **Type-based expiry** | Volatile state ages out (~2 days) while identity never does, so recall stays current automatically. |
+
+Everything is taggable, expirable, and deletable — you always see and control what's
+remembered.
+
+## Quick start
+
+Jamgate runs **locally** — your memory never leaves your machine. Requires Node.js 20+.
+No install step: `npx` fetches and runs it on demand.
+
+### Claude Code
+
+```bash
+claude mcp add jamgate -- npx jamgate
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "jamgate": {
+      "command": "npx",
+      "args": ["jamgate"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "jamgate": {
+      "command": "npx",
+      "args": ["jamgate"]
+    }
+  }
+}
+```
+
+Restart the agent. It now has three tools:
+
+- **`save_memory`** — store a durable fact. The gate rejects junk, drops exact
+  duplicates, supersedes outdated facts by recency (pass a `subject` like
+  `operating-system` so a newer fact retires the older one — or let the gate derive one),
+  and refers trust conflicts back to you.
+- **`recall_memory`** — fetch what's known, relevant to a query (active facts only).
+- **`forget_memory`** — delete a memory by id.
+
+Your memory lives in `~/.jamgate/memory.json`. Same machine, every agent → one shared
+memory.
+
+## Optional: local semantic search
+
+By default, recall is **fuzzy lexical** matching (stemming, typo-tolerance, trigrams) —
+fast, deterministic, and dependency-free, but blind to synonyms. To also match on
+*meaning* (so "automobile" recalls a memory about your "car"), install the optional
+embedding backend:
+
+```bash
+npm install @huggingface/transformers
+```
+
+On first use it downloads a small sentence-embedding model (all-MiniLM-L6-v2, ~23 MB,
+quantized) and runs it **entirely on your machine — no text is ever sent to any cloud
+AI.** With it enabled, recall blends semantic similarity into the ranking, and a save
+that is semantically near-identical to an existing memory comes back as a
+`possible_duplicate` for you to confirm. **If the package isn't installed, Jamgate runs
+on fuzzy recall — nothing breaks.**
+
+## Configuration
+
+All configuration is via environment variables; every one has a sensible default.
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `JAMGATE_STORE` | `~/.jamgate/memory.json` | Path to the memory store file. |
+| `JAMGATE_EMBEDDINGS` | auto | `off` disables the semantic layer even if the model is installed. |
+| `JAMGATE_DUP_THRESHOLD` | `0.88` | Semantic near-duplicate sensitivity (0–1); higher = stricter. |
+| `JAMGATE_GATE_LOG` | on | `off` disables the local decision log. |
+| `JAMGATE_TTL_<TYPE>_DAYS` | per type | Override the freshness window for a memory type, e.g. `JAMGATE_TTL_PROJECT_DAYS=180`. |
+
+## How it compares
+
+Jamgate is deliberately small and opinionated. It is **not** trying to be a hosted memory
+platform or a knowledge graph — it's the write-time quality layer those systems are
+weakest at, packaged as a drop-in local MCP server.
+
+| | **Jamgate** | **Mem0 / OpenMemory** | **Zep / Graphiti** |
+| --- | --- | --- | --- |
+| Core model | Write-time quality **gate** over a flat store | LLM-extracted memory layer | Temporal knowledge **graph** |
+| Where memory lives | Local file on your machine | Hosted platform or self-hosted store | Graph server (self-hosted or cloud) |
+| Their strength | — | Rich extraction, broad SDKs/integrations, scale | Powerful entity/relationship & temporal modeling |
+| Gate **before** write | ✅ core design | Partial (dedup/update) | Partial |
+| Source-trust hierarchy | ✅ | — | — |
+| Refers conflicts back to you | ✅ | — | — |
+| LLM calls of its own | ❌ none | ✅ required | ✅ required |
+| Dependencies / infra | 1 dep, no server | SDK + service/DB | Graph DB + service |
+| Best for | Keeping one shared personal memory clean, locally | Full-featured app-scale memory | Complex relational/temporal reasoning |
+
+Mem0, OpenMemory, Zep, and Graphiti are capable systems built for different goals; if you
+need managed scale or graph reasoning, they're the right tool. Jamgate's bet is that for
+*personal* cross-agent memory, the hard part is quality at write time — and that it should
+be local, free, and one command to install.
+
+## Privacy
+
+- **Everything is local.** The memory store, the gate, and (if enabled) the embedding
+  model all run on your machine. Jamgate makes **no network calls** and talks to no cloud
+  AI.
+- **The decision log is local too.** Every gate decision (saved / duplicate / superseded /
+  conflict / possible_duplicate / rejected, with its reason) is appended to
+  `~/.jamgate/gate.log`, a strictly local, size-capped JSONL file that rotates
+  automatically and **never leaves your machine**. It exists to collect real usage data
+  for a future local quality classifier. Disable it with `JAMGATE_GATE_LOG=off`.
+- **Nothing leaves the machine** — no telemetry, no accounts, no keys.
+
+## Status
+
+Early but real, and now installable with one command. The MVP core, robustness, and
+intelligence layers all work today (see [`CHANGELOG.md`](./CHANGELOG.md) for the full
+0.1.0 scope):
+
+- **Gate core** — rule pre-filter, exact dedup, time-aware supersession, source-trust
+  conflict guard, over a local flat-file store.
+- **Robustness** — atomic durable writes, type-based expiry, concurrency-safe locking,
+  automatic schema migration.
+- **Intelligence** — trusted client provenance, fuzzy recall, optional local embeddings
+  with graceful fallback, auto-subject derivation, local decision log.
+
+Verified end-to-end over the MCP protocol and covered by an automated test suite (89
+tests) on Node 20.x and 22.x. Next: a thin classifier for ambiguous cases (trained on the
+local decision log) and multi-device sync (see [`DECISIONS.md`](./DECISIONS.md)).
+**Goal: impact, not profit — open-source (MIT), built in the open.**
+
+## Development
+
+```bash
+npm install
+npm run build   # compile TypeScript to dist/
+npm test        # compile and run the test suite (built-in node:test, no extra deps)
+```
+
+CI runs the build and tests on Node 20.x and 22.x for every push and pull request.
+
+## Contributing
+
+This is an impact project. The most valuable contributions are around **write-time
+quality** (selective capture, dedup, contradiction handling, expiry) — the part the whole
+field is weakest at. See [`AGENTS.md`](./AGENTS.md) to get oriented, then
+[`RULES.md`](./RULES.md).
+
+## License
+
+[MIT](./LICENSE)

package/dist/embeddings/embedder.js

@@ -0,0 +1,57 @@
+// Optional local embedding backend (Phase 3, item 4).
+//
+// Jamgate's base install stays zero-heavy-deps: `@huggingface/transformers` is an OPTIONAL
+// peer dependency, not a hard one. This module dynamically imports it only on demand and
+// degrades gracefully — if the package (or its model) is absent, `loadTransformersEmbedder`
+// returns null and the store runs on fuzzy lexical recall alone. Nothing here runs in CI:
+// loading the model would hit the network to download it. The store depends only on the
+// small `Embedder` interface, so tests inject a deterministic mock instead.
+//
+// Model: all-MiniLM-L6-v2 (the Xenova ONNX port), 384-dimensional sentence embeddings,
+// mean-pooled and L2-normalized. It is a ~23 MB quantized download, fetched locally on
+// first use and cached by Transformers.js under its own cache dir. No text ever leaves the
+// machine — inference is fully local (RULES: never send data to any cloud AI; D-026).
+/** The near-duplicate similarity threshold, overridable via env. Falls back to the module
+ *  default when unset or garbage. Kept here so the whole embedding config lives in one place. */
+export function resolveDupThreshold(env = process.env) {
+    const raw = env.JAMGATE_DUP_THRESHOLD;
+    if (raw === undefined)
+        return undefined; // caller uses its own default
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0 || n > 1)
+        return undefined;
+    return n;
+}
+const MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+const DIMENSIONS = 384;
+/**
+ * Try to build the real Transformers.js embedder. Returns null (never throws) when the
+ * optional dependency or the model is unavailable, so the caller can fall back to fuzzy
+ * recall. Embedding is opt-out via `JAMGATE_EMBEDDINGS=off`.
+ *
+ * The heavy import is dynamic and behind a runtime string so the base build never resolves
+ * the module at type-check time and a missing package is a graceful null, not a crash.
+ */
+export async function loadTransformersEmbedder(env = process.env) {
+    const flag = env.JAMGATE_EMBEDDINGS?.trim().toLowerCase();
+    if (flag && ["off", "none", "0", "false"].includes(flag))
+        return null;
+    try {
+        const pkg = "@huggingface/transformers";
+        const mod = (await import(/* @vite-ignore */ pkg));
+        const extractor = await mod.pipeline("feature-extraction", MODEL_ID);
+        return {
+            id: MODEL_ID,
+            dimensions: DIMENSIONS,
+            async embed(text) {
+                const output = await extractor(text, { pooling: "mean", normalize: true });
+                return Array.from(output.data);
+            },
+        };
+    }
+    catch (err) {
+        // Package missing, model download blocked, or runtime error → degrade to fuzzy recall.
+        console.error("jamgate: optional embeddings unavailable, falling back to fuzzy recall:", err?.message ?? err);
+        return null;
+    }
+}

package/dist/embeddings/vector.js

@@ -0,0 +1,54 @@
+// Pure vector math for the optional embedding layer (Phase 3, item 4).
+//
+// This module is deliberately dependency-free and has NO knowledge of any ML runtime — it
+// is just the arithmetic that the semantic layer needs: cosine similarity, blending a
+// semantic score with the fuzzy lexical score, and the near-duplicate threshold. Keeping it
+// pure means it is fully unit-testable in CI with hand-built vectors, no model download.
+/** Default similarity at/above which two texts are treated as semantic near-duplicates.
+ *  Tuned for all-MiniLM-L6-v2 normalized embeddings: paraphrases of the same statement
+ *  sit high (~0.85–0.95) while genuinely different facts (even similar phrasing like
+ *  "uses Windows" vs "uses Linux") sit well below. Overridable via env (see embedder). */
+export const DEFAULT_DUP_THRESHOLD = 0.88;
+/** Blend weights for combining the lexical (fuzzy) score with the semantic score during
+ *  recall. Semantic leads because it is what adds synonym reach; fuzzy anchors on exact
+ *  surface matches the embedding can under-weight. Both operands are expected in [0, 1]. */
+const SEMANTIC_WEIGHT = 0.6;
+const LEXICAL_WEIGHT = 0.4;
+/** Minimum semantic similarity for an embedding match to pull an otherwise lexically
+ *  irrelevant memory into recall. High enough to admit true synonyms (~0.6–0.8 on MiniLM)
+ *  while excluding the moderate baseline similarity (~0.2–0.4) unrelated short texts show —
+ *  without this floor, semantic noise would flood recall. */
+export const DEFAULT_SEMANTIC_MIN = 0.5;
+/**
+ * Cosine similarity of two equal-length vectors, in [-1, 1]. Returns 0 for a zero vector
+ * or a length mismatch (defensive: a corrupt/older embedding must not throw during recall).
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/**
+ * Blend a lexical (fuzzy) relevance score with a semantic similarity into one recall score.
+ * Clamps the semantic input to [0, 1] first (cosine can be slightly negative for unrelated
+ * text) so the blend stays in [0, 1] and comparable to the pure-fuzzy path.
+ */
+export function blendRelevance(lexical, semantic) {
+    const sem = Math.max(0, Math.min(1, semantic));
+    const lex = Math.max(0, Math.min(1, lexical));
+    return LEXICAL_WEIGHT * lex + SEMANTIC_WEIGHT * sem;
+}
+/** Is `similarity` at/above the near-duplicate threshold? */
+export function isNearDuplicate(similarity, threshold = DEFAULT_DUP_THRESHOLD) {
+    return similarity >= threshold;
+}

package/dist/gate/log.js

@@ -0,0 +1,77 @@
+// Local-only gate decision log (Phase 3, item 3).
+//
+// Every save runs through the gate and comes out with a decision: saved, duplicate,
+// superseded, conflict, possible_duplicate, or rejected — each with a reason. Appending
+// those decisions to a local JSONL file gives us real, labelled data to later train the
+// thin "is this worth keeping?" classifier (D-004) on actual usage instead of guesses.
+//
+// STRICTLY LOCAL. This log never leaves the machine — same local-first promise as the
+// store (D-010). It lives next to the store (~/.jamgate/gate.log by default), is
+// size-capped with single-file rotation so it can't grow without bound, and logging can be
+// turned off entirely (JAMGATE_GATE_LOG=off). Logged text is truncated to keep lines small
+// (so appends stay atomic on POSIX) and to bound the footprint. Logging is best-effort: a
+// failure to write the log must NEVER fail or slow the user's save, so all errors are
+// swallowed to stderr.
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const DEFAULT_PATH = join(homedir(), ".jamgate", "gate.log");
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024; // 5 MiB
+const DEFAULT_MAX_TEXT_CHARS = 500;
+/** Resolve logging config from the environment (all overridable). `JAMGATE_GATE_LOG` sets
+ *  the path; `off`/`none`/`0` disables. `JAMGATE_GATE_LOG_MAX_BYTES` caps the size. */
+export function resolveGateLogConfig(env = process.env) {
+    const raw = env.JAMGATE_GATE_LOG?.trim();
+    const disabled = raw !== undefined && ["off", "none", "0", ""].includes(raw.toLowerCase());
+    const path = disabled ? null : raw && raw.length > 0 ? raw : DEFAULT_PATH;
+    const maxBytesRaw = Number(env.JAMGATE_GATE_LOG_MAX_BYTES);
+    const maxBytes = Number.isFinite(maxBytesRaw) && maxBytesRaw > 0 ? maxBytesRaw : DEFAULT_MAX_BYTES;
+    return { path, maxBytes, maxTextChars: DEFAULT_MAX_TEXT_CHARS };
+}
+/**
+ * Append one gate decision to the log. Best-effort and non-throwing: any error is
+ * swallowed to stderr so logging can never break a save. Rotates the log to `<path>.1`
+ * (overwriting the previous rotation) once it exceeds `maxBytes`, bounding disk use to
+ * roughly 2× the cap.
+ */
+export async function appendGateLog(entry, config = resolveGateLogConfig()) {
+    if (config.path === null)
+        return; // logging disabled
+    try {
+        const dir = dirname(config.path);
+        await fs.mkdir(dir, { recursive: true });
+        await rotateIfNeeded(config.path, config.maxBytes);
+        const record = {
+            ts: new Date().toISOString(),
+            decision: entry.decision,
+            ...(entry.reason ? { reason: entry.reason } : {}),
+            ...(entry.type ? { type: entry.type } : {}),
+            ...(entry.subject ? { subject: entry.subject } : {}),
+            ...(entry.source ? { source: entry.source } : {}),
+            ...(entry.client ? { client: entry.client } : {}),
+            text: truncate(entry.text, config.maxTextChars),
+        };
+        await fs.appendFile(config.path, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    catch (err) {
+        // Never let a diagnostic log break the actual save.
+        console.error("jamgate: gate log write failed (ignored):", err);
+    }
+}
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+/** Rotate `path` → `path.1` when it grows past `maxBytes`. Single-file rotation keeps the
+ *  most recent two generations; older data is intentionally discarded (this is a rolling
+ *  training buffer, not an audit log). */
+async function rotateIfNeeded(path, maxBytes) {
+    try {
+        const { size } = await fs.stat(path);
+        if (size >= maxBytes)
+            await fs.rename(path, `${path}.1`);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err; // no file yet → nothing to rotate
+    }
+}

package/dist/gate/prefilter.js

@@ -0,0 +1,17 @@
+/**
+ * Cheap rule pre-filter (RULES §5.1): kill the obvious junk before spending any AI.
+ * This is layer 1 of the gate only — salience scoring and the thin classifier come later.
+ */
+const PLEASANTRIES = new Set([
+    "hi", "hello", "hey", "thanks", "thank you", "ok", "okay", "k",
+    "cool", "nice", "lol", "yes", "no", "sure", "yep", "nope", "bye",
+]);
+export function prefilter(text) {
+    const t = text.trim();
+    if (t.length < 4)
+        return { ok: false, reason: "too short" };
+    if (PLEASANTRIES.has(t.toLowerCase())) {
+        return { ok: false, reason: "pleasantry / no durable content" };
+    }
+    return { ok: true };
+}

package/dist/gate/relevance.js

@@ -0,0 +1,138 @@
+// Fuzzy, dependency-free relevance scoring for recall (Phase 3, item 2).
+//
+// The MVP recall scored by crude word overlap: for each query word, does the memory text
+// contain it as a substring? That is brittle — "projects" misses "project", "berln" misses
+// "berlin", and "cat" spuriously matches "category". This module replaces it with a
+// deterministic, ML-free scorer that is markedly more forgiving of the small surface
+// variations real queries carry, while staying fully local and reproducible.
+//
+// It is NOT semantic: it has no notion that "car" and "automobile" mean the same thing.
+// Synonyms are the job of the optional embedding layer (Phase 3, item 4); this layer earns
+// its keep on morphology and typos, deterministically and with zero dependencies.
+//
+// The score blends two signals:
+//   1. weighted token overlap — each query token scored by its best fuzzy match among the
+//      text tokens (exact/stemmed match = 1, else a trigram-similarity partial credit),
+//      weighted so longer, more-informative tokens count for more and stopwords for nothing;
+//   2. whole-string trigram similarity — a character-level Dice coefficient that rewards
+//      overall shared substance and catches matches the tokenizer splits apart.
+// Token overlap dominates (it is the precise signal); trigram similarity is a smaller
+// tie-breaker that mainly helps on typos and word-boundary noise.
+/** Blend weight: token overlap is the primary signal, trigram a secondary tie-breaker. */
+const TOKEN_WEIGHT = 0.75;
+const TRIGRAM_WEIGHT = 0.25;
+/** Below this, a memory is treated as not matching the query at all (keeps trigram noise
+ *  from surfacing unrelated memories). Chosen so a single solid token match clears it. */
+export const MIN_RELEVANCE = 0.1;
+/** A fuzzy token match below this trigram similarity earns no credit. Prevents two words
+ *  that merely share a first letter ("berlin"/"build") from scoring as a near-match, while
+ *  still crediting genuine typos ("berlin"/"berln" ≈ 0.6). */
+const FUZZY_TOKEN_FLOOR = 0.4;
+/** Common function words that carry no discriminating signal. Deliberately small — only
+ *  words that are near-always noise in a short factual memory. If a query is made ENTIRELY
+ *  of these, we fall back to using them so the query still matches something. */
+const STOPWORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "by", "do", "does", "for", "from",
+    "has", "have", "how", "i", "in", "is", "it", "its", "me", "my", "of", "on",
+    "or", "so", "that", "the", "their", "them", "they", "this", "to", "was", "were",
+    "what", "when", "where", "which", "who", "why", "with", "you", "your",
+]);
+/** Split text into lowercase alphanumeric tokens, punctuation stripped. */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+/**
+ * Stemming-lite: strip a few common English inflectional suffixes so "projects",
+ * "projecting" and "project" collapse to one stem. Intentionally crude and conservative
+ * (no Porter stemmer, no dependency) — it only trims suffixes when a reasonable stem
+ * length remains, so short tokens are left intact rather than mangled.
+ */
+export function stem(token) {
+    let t = token;
+    const trim = (suffix, min) => {
+        if (t.length >= suffix.length + min && t.endsWith(suffix)) {
+            t = t.slice(0, -suffix.length);
+            return true;
+        }
+        return false;
+    };
+    // Order matters: try longer/derivational suffixes before the bare plural -s.
+    trim("ing", 3) || trim("edly", 3) || trim("ed", 3) || trim("ly", 3);
+    trim("ies", 2) && (t += "y"); // "memories" -> "memory"
+    trim("es", 3) || trim("s", 3);
+    return t;
+}
+/** Content stems of a text: tokenized, stopwords removed, each stemmed. Falls back to the
+ *  full stemmed token list when the text is nothing but stopwords, so it never goes empty
+ *  for a non-empty input. */
+export function contentStems(text) {
+    const tokens = tokenize(text);
+    const content = tokens.filter((t) => !STOPWORDS.has(t));
+    const kept = content.length > 0 ? content : tokens;
+    return kept.map(stem);
+}
+/** Character trigrams of a string (padded so short strings still produce trigrams). */
+function trigrams(s) {
+    const padded = `  ${s} `;
+    const grams = new Set();
+    for (let i = 0; i < padded.length - 2; i++)
+        grams.add(padded.slice(i, i + 3));
+    return grams;
+}
+/** Sørensen–Dice similarity of two strings over character trigrams, in [0, 1]. */
+export function trigramSimilarity(a, b) {
+    if (a === b)
+        return 1;
+    if (!a || !b)
+        return 0;
+    const ga = trigrams(a);
+    const gb = trigrams(b);
+    let shared = 0;
+    for (const g of ga)
+        if (gb.has(g))
+            shared++;
+    return (2 * shared) / (ga.size + gb.size);
+}
+/** How well a single query stem matches a single text stem: exact = 1, else trigram
+ *  partial credit (so "berln" still scores against "berlin"). */
+function tokenSimilarity(q, t) {
+    if (q === t)
+        return 1;
+    const sim = trigramSimilarity(q, t);
+    return sim >= FUZZY_TOKEN_FLOOR ? sim : 0;
+}
+/**
+ * Relevance of `text` to `query`, in [0, 1]. Deterministic and dependency-free.
+ * 0 means no meaningful overlap. Higher is more relevant.
+ */
+export function relevanceScore(query, text) {
+    const qStems = contentStems(query);
+    const tStems = contentStems(text);
+    if (qStems.length === 0 || tStems.length === 0)
+        return 0;
+    // Weighted token overlap: each query stem earns its best fuzzy match among text stems,
+    // weighted by stem length so a hit on "operating" counts for more than a hit on "os".
+    let weighted = 0;
+    let totalWeight = 0;
+    for (const q of qStems) {
+        const weight = q.length;
+        let best = 0;
+        for (const t of tStems) {
+            const sim = tokenSimilarity(q, t);
+            if (sim > best)
+                best = sim;
+            if (best === 1)
+                break;
+        }
+        weighted += weight * best;
+        totalWeight += weight;
+    }
+    const tokenScore = totalWeight > 0 ? weighted / totalWeight : 0;
+    // Whole-string trigram similarity over the stemmed content — a smaller corroborating
+    // signal that catches shared substance the token loop misses.
+    const trigramScore = trigramSimilarity(qStems.join(" "), tStems.join(" "));
+    return TOKEN_WEIGHT * tokenScore + TRIGRAM_WEIGHT * trigramScore;
+}