jamgate 0.1.0

package/dist/gate/subject.js

@@ -0,0 +1,73 @@
+// Best-effort automatic subject derivation (Phase 3, item 5).
+//
+// `subject` is what a memory is *about* — the key that drives time-aware supersession
+// (RULES §2.3, D-015): a newer memory with the same subject retires the older one. The
+// calling agent is asked to supply it, but often won't. When it's missing, we try to derive
+// one from the text with plain, deterministic rules — NO ML.
+//
+// This is deliberately CONSERVATIVE. A wrong subject would wrongly retire an unrelated
+// memory, so the bar for auto-assigning is high: we only return a subject when a rule
+// matches with confidence, and otherwise leave it unset (undefined). Missing a subject is
+// safe (the memory simply isn't subject-supersedable); inventing a wrong one is not.
+//
+// Two layers, high-confidence first:
+//   1. a curated keyword map for the most common, unambiguous subjects (location, OS, …);
+//   2. a possessive/copula pattern — "<determiner> <noun phrase> is/are …" — that lifts the
+//      noun phrase as the subject ("my favorite color is blue" → "favorite-color").
+// The output is a lowercase, hyphenated key, matching the convention used elsewhere.
+const STOPWORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "has", "have",
+    "in", "is", "it", "its", "of", "on", "or", "that", "the", "their", "this", "to",
+    "was", "were", "with",
+]);
+/** High-confidence keyword → subject rules, checked in order (first match wins). Each
+ *  pattern is anchored on distinctive words so it rarely fires by accident. */
+const KEYWORD_RULES = [
+    { subject: "location", pattern: /\b(lives?|living|located|resides?|based)\b/ },
+    {
+        subject: "operating-system",
+        pattern: /\boperating system\b|\b(linux|windows|macos|ubuntu|debian|fedora|arch)\b/,
+    },
+    { subject: "email", pattern: /\bemail\b|[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/ },
+    { subject: "timezone", pattern: /\btime ?zone\b|\butc[+-]?\d/ },
+    { subject: "name", pattern: /\b(name is|named|call me|goes by)\b/ },
+    {
+        subject: "programming-language",
+        pattern: /\b(programs?|coding|codes?|develops?|writes?) in\b|\bprogramming language\b/,
+    },
+    { subject: "current-project", pattern: /\b(working on|building|developing|current project)\b/ },
+];
+/** Possessive/copula extractor: "<det> <noun phrase> is/are …". Captures the noun phrase. */
+const COPULA = /\b(?:my|your|their|his|her|our|its|the|[a-z]+'s)\s+([a-z]+(?:\s+[a-z]+){0,2})\s+(?:is|are|was|were)\b/;
+/**
+ * Derive a best-effort subject from `text`, or undefined when no rule fires confidently.
+ * Deterministic and dependency-free.
+ */
+export function deriveSubject(text) {
+    const lower = text.toLowerCase();
+    for (const { subject, pattern } of KEYWORD_RULES) {
+        if (pattern.test(lower))
+            return subject;
+    }
+    const m = COPULA.exec(lower);
+    if (m) {
+        const phrase = normalizePhrase(m[1]);
+        if (phrase)
+            return phrase;
+    }
+    return undefined; // not confident → leave unset (safe)
+}
+/** Turn a captured noun phrase into a subject key: drop stopwords, keep 1–3 content tokens,
+ *  hyphenate. Returns undefined if nothing meaningful remains. */
+function normalizePhrase(phrase) {
+    const tokens = phrase
+        .split(/\s+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0 && !STOPWORDS.has(t));
+    if (tokens.length === 0 || tokens.length > 3)
+        return undefined;
+    // Guard against a lone ultra-generic token producing a useless subject.
+    if (tokens.length === 1 && tokens[0].length < 3)
+        return undefined;
+    return tokens.join("-");
+}

package/dist/index.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { pathToFileURL } from "node:url";
+import { FileStore } from "./store/fileStore.js";
+import { loadTransformersEmbedder, resolveDupThreshold } from "./embeddings/embedder.js";
+import { prefilter } from "./gate/prefilter.js";
+import { deriveSubject } from "./gate/subject.js";
+import { appendGateLog, resolveGateLogConfig, } from "./gate/log.js";
+/**
+ * Build the Jamgate MCP server around a given store. Factored out of the stdio bootstrap
+ * so tests can drive the real handlers over an in-memory transport (e.g. to prove that
+ * client provenance is captured from the handshake, D-024) without spawning a process.
+ */
+export function createServer(store, gateLog = resolveGateLogConfig()) {
+    const server = new Server({ name: "jamgate", version: "0.1.0" }, { capabilities: { tools: {} } });
+    /** The MCP client behind the current connection, taken from the `clientInfo` the client
+     *  sent in the `initialize` handshake (D-024). This is server-observed provenance — the
+     *  calling agent cannot spoof it through tool arguments. Undefined until the handshake
+     *  completes or if the client sent no name. */
+    function clientInfoFromHandshake() {
+        const impl = server.getClientVersion();
+        if (!impl?.name)
+            return undefined;
+        return { name: impl.name, version: impl.version };
+    }
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "save_memory",
+                description: "Save a durable memory about the user through the Jamgate quality gate. " +
+                    "Only call this for things worth remembering across sessions — identity, " +
+                    "projects, preferences, lasting state — not chatter. Trivial or duplicate " +
+                    "input is rejected by the gate.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "The memory, as a clear standalone statement." },
+                        type: {
+                            type: "string",
+                            enum: ["identity", "project", "preference", "state"],
+                            description: "Which memory layer this belongs to (RULES §4).",
+                        },
+                        subject: {
+                            type: "string",
+                            description: "What this memory is about, e.g. 'operating-system', 'location', " +
+                                "'current-project'. If a newer memory shares a subject with an older one, " +
+                                "the newer replaces it (time-aware supersession). Strongly recommended; " +
+                                "if omitted, the gate derives a best-effort subject from the text.",
+                        },
+                        source: {
+                            type: "string",
+                            enum: ["agent-inferred", "user-confirmed", "user-explicit"],
+                            description: "Where this memory came from. Defaults to agent-inferred.",
+                        },
+                    },
+                    required: ["text"],
+                },
+            },
+            {
+                name: "recall_memory",
+                description: "Recall stored memories about the user relevant to a query.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string", description: "What to recall. Empty returns the most recent." },
+                        limit: { type: "number", description: "Max results (default 5)." },
+                    },
+                },
+            },
+            {
+                name: "forget_memory",
+                description: "Delete a stored memory by its id.",
+                inputSchema: {
+                    type: "object",
+                    properties: { id: { type: "string", description: "The memory id to forget." } },
+                    required: ["id"],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name } = req.params;
+        const args = (req.params.arguments ?? {});
+        if (name === "save_memory") {
+            const text = String(args.text ?? "");
+            const client = clientInfoFromHandshake();
+            const verdict = prefilter(text);
+            if (!verdict.ok) {
+                // Record the rejection too — the classifier learns from what the gate turns away.
+                await appendGateLog({
+                    decision: "rejected",
+                    reason: verdict.reason,
+                    type: args.type ? String(args.type) : undefined,
+                    subject: args.subject ? String(args.subject) : undefined,
+                    source: args.source ? String(args.source) : undefined,
+                    client: client?.name,
+                    text,
+                }, gateLog);
+                return { content: [{ type: "text", text: `Rejected by gate: ${verdict.reason}.` }] };
+            }
+            // Use the agent's subject when given; otherwise try to derive one conservatively
+            // (D-027). A derived subject only fires on a confident rule match, else stays unset.
+            const subject = args.subject ? String(args.subject) : deriveSubject(text);
+            const result = await store.save({
+                text,
+                type: args.type,
+                source: args.source ?? "agent-inferred",
+                subject,
+                // Provenance from the MCP initialize handshake, not the agent's tool arguments (D-024).
+                client,
+            });
+            // Log the gate's decision to the local-only training buffer (D-025).
+            const decision = result.action === "created" ? "saved" : result.action;
+            await appendGateLog({
+                decision,
+                type: result.memory.type,
+                subject: result.memory.subject,
+                source: result.memory.source,
+                client: result.memory.client?.name,
+                text: result.memory.text,
+            }, gateLog);
+            let msg;
+            if (result.action === "duplicate") {
+                msg = `Already known (no duplicate added): "${result.memory.text}" [id ${result.memory.id}]`;
+            }
+            else if (result.action === "superseded") {
+                const old = (result.retired ?? []).map((m) => `"${m.text}"`).join(", ");
+                msg =
+                    `Saved and superseded by recency — retired ${old} in favor of ` +
+                        `"${result.memory.text}" [id ${result.memory.id}]`;
+            }
+            else if (result.action === "conflict") {
+                const conflicts = (result.conflictsWith ?? [])
+                    .map((m) => `"${m.text}" (${m.source})`)
+                    .join(", ");
+                msg =
+                    `Not saved — conflict on subject "${result.memory.subject}". A more-trusted ` +
+                        `memory already exists: ${conflicts}. The new fact "${result.memory.text}" came ` +
+                        `from a less-trusted source (${result.memory.source}). Confirm with the user; to ` +
+                        `apply it, re-save with source "user-confirmed" or "user-explicit".`;
+            }
+            else if (result.action === "possible_duplicate") {
+                const near = (result.possibleDuplicates ?? [])
+                    .map((d) => `"${d.memory.text}" [id ${d.memory.id}] (~${d.similarity.toFixed(2)})`)
+                    .join(", ");
+                msg =
+                    `Not saved — "${result.memory.text}" looks like a semantic duplicate of an ` +
+                        `existing memory: ${near}. If it is genuinely the same fact, nothing to do. If it ` +
+                        `is a distinct fact or an update, re-save with a \`subject\` so the gate treats it ` +
+                        `as its own memory (or a time-aware update of that subject).`;
+            }
+            else {
+                msg = `Saved: "${result.memory.text}" [id ${result.memory.id}]`;
+            }
+            return { content: [{ type: "text", text: msg }] };
+        }
+        if (name === "recall_memory") {
+            const hits = await store.recall(String(args.query ?? ""), Number(args.limit ?? 5));
+            if (hits.length === 0)
+                return { content: [{ type: "text", text: "No matching memories." }] };
+            const body = hits
+                .map((m) => `- [${m.type ?? "untyped"}] ${m.text} (id ${m.id}, ${m.createdAt})`)
+                .join("\n");
+            return { content: [{ type: "text", text: body }] };
+        }
+        if (name === "forget_memory") {
+            const ok = await store.forget(String(args.id ?? ""));
+            return { content: [{ type: "text", text: ok ? "Forgotten." : "No memory with that id." }] };
+        }
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    });
+    return server;
+}
+async function main() {
+    // Optional local embeddings (D-026): try to load the model; null → fuzzy recall only.
+    // Loading is lazy and best-effort so the base install and offline/CI runs work unchanged.
+    const embedder = await loadTransformersEmbedder();
+    if (embedder)
+        console.error(`jamgate: semantic embeddings active (${embedder.id})`);
+    else
+        console.error("jamgate: running on fuzzy recall (no embedding model loaded)");
+    // Depend on the adapter contract, not a concrete backend (D-019).
+    const store = new FileStore(undefined, {
+        embedder: embedder ?? undefined,
+        dupThreshold: resolveDupThreshold(),
+    });
+    const server = createServer(store);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the MCP channel; logs must go to stderr.
+    console.error("jamgate MCP server running on stdio");
+}
+// Only bootstrap stdio when run as the CLI entrypoint, not when imported by a test.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((err) => {
+        console.error("jamgate fatal:", err);
+        process.exit(1);
+    });
+}

package/dist/store/fileStore.js

@@ -0,0 +1,274 @@
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { CURRENT_SCHEMA_VERSION, migrate } from "./schema.js";
+import { computeExpiresAt, isCompactable, isExpired, resolveGraceMs, resolveTtlPolicy, } from "./ttl.js";
+import { withFileLock } from "./lock.js";
+import { MIN_RELEVANCE, relevanceScore } from "../gate/relevance.js";
+import { DEFAULT_DUP_THRESHOLD, DEFAULT_SEMANTIC_MIN, blendRelevance, cosineSimilarity, } from "../embeddings/vector.js";
+/** How much we trust a memory by where it came from. A lower-trust source must not
+ *  silently overwrite a higher-trust one — that's a contradiction to confirm, not an
+ *  update to apply (RULES §2.3). */
+const TRUST = {
+    "agent-inferred": 1,
+    "user-confirmed": 2,
+    "user-explicit": 3,
+};
+const DEFAULT_PATH = join(homedir(), ".jamgate", "memory.json");
+/**
+ * The default store for the MVP (RULES §8: file/SQLite first, BYO stores later).
+ * Implements the `MemoryStore` adapter contract (D-019) so a hosted store can drop in
+ * later without touching the gate. Real, not a stub — save/recall/forget all persist.
+ *
+ * Phase 2 robustness (see DECISIONS D-020..D-023):
+ *  - writes are atomic + durable (temp file + fsync + rename),
+ *  - records expire by type and are compacted once long-dead,
+ *  - concurrent writers on one host are serialized by a lock file,
+ *  - the file carries a schemaVersion and old formats migrate automatically.
+ *
+ * Phase 3 (D-026): an OPTIONAL embedder can be injected. When present, saves carry a local
+ * semantic embedding, recall blends semantic similarity with the fuzzy lexical score, and a
+ * near-duplicate is flagged as "possible_duplicate". When absent, everything falls back to
+ * fuzzy-only recall — the base install needs no ML runtime, and CI runs this path.
+ */
+export class FileStore {
+    path;
+    lockPath;
+    ttl;
+    graceMs;
+    embedder;
+    dupThreshold;
+    constructor(path = process.env.JAMGATE_STORE ?? DEFAULT_PATH, opts = {}) {
+        this.path = path;
+        this.lockPath = `${path}.lock`;
+        // Read policy once at construction so a single store instance is internally
+        // consistent; a fresh instance picks up any changed env overrides.
+        this.ttl = resolveTtlPolicy();
+        this.graceMs = resolveGraceMs();
+        this.embedder = opts.embedder;
+        this.dupThreshold = opts.dupThreshold ?? DEFAULT_DUP_THRESHOLD;
+    }
+    /** Best-effort embedding: returns the vector, or undefined if no embedder is configured
+     *  or the embedder fails (recall/near-dup then degrade to fuzzy for this call). */
+    async embed(text) {
+        if (!this.embedder)
+            return undefined;
+        try {
+            return await this.embedder.embed(text);
+        }
+        catch (err) {
+            console.error("jamgate: embedding failed, using fuzzy recall for this op:", err);
+            return undefined;
+        }
+    }
+    /** Load the store, migrating any older on-disk format to the current schema in memory
+     *  (the upgraded shape is persisted on the next write). */
+    async load() {
+        let raw;
+        try {
+            raw = await fs.readFile(this.path, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                return { schemaVersion: CURRENT_SCHEMA_VERSION, memories: [] };
+            }
+            throw err;
+        }
+        if (raw.trim() === "")
+            return { schemaVersion: CURRENT_SCHEMA_VERSION, memories: [] };
+        return migrate(JSON.parse(raw), this.ttl);
+    }
+    async readAll() {
+        return (await this.load()).memories;
+    }
+    /**
+     * Atomic, durable write (Phase 2, item 1). Serialize to a temp file in the SAME
+     * directory, fsync it, then rename over the target. `rename(2)` is atomic on a POSIX
+     * local filesystem, so a concurrent reader — or a crash mid-write — sees either the
+     * old file or the new one, never a half-written (torn) store. The temp lives in the
+     * same directory so the rename stays on one filesystem (a cross-device rename is not
+     * atomic).
+     */
+    async writeAll(memories) {
+        const dir = dirname(this.path);
+        await fs.mkdir(dir, { recursive: true });
+        const file = { schemaVersion: CURRENT_SCHEMA_VERSION, memories };
+        const data = JSON.stringify(file, null, 2);
+        const tmp = join(dir, `.${basename(this.path)}.${randomUUID()}.tmp`);
+        try {
+            await this.persist(tmp, data);
+            await fs.rename(tmp, this.path);
+        }
+        catch (err) {
+            await fs.rm(tmp, { force: true }); // never leave an orphaned temp behind
+            throw err;
+        }
+    }
+    /** Write `data` to `tmpPath` and fsync it to disk. Factored out as a seam so a test
+     *  can simulate a crash mid-write and prove the committed store survives intact. */
+    async persist(tmpPath, data) {
+        const handle = await fs.open(tmpPath, "w");
+        try {
+            await handle.writeFile(data, "utf8");
+            await handle.sync(); // flush to disk before the rename commits the new file
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /**
+     * Write a memory through the stateful checks:
+     *  - exact-duplicate dedup (RULES §2.2)
+     *  - time-aware supersession (RULES §2.3, D-015): a newer memory with the same
+     *    `subject` retires the old one by recency (kept, not deleted, for audit).
+     *  - contradiction guard (RULES §2.3): a lower-trust source can't silently overwrite
+     *    a higher-trust one on the same subject → returns "conflict" for confirmation.
+     *
+     * The whole read-modify-write runs under the store lock (re-reading the file fresh
+     * inside the lock), so a second process saving at the same time cannot lose this write.
+     */
+    async save(input) {
+        return this.withLock(() => this.saveLocked(input));
+    }
+    /** Ensure the store directory exists (the lock file lives there too), then run `fn`
+     *  while holding the store lock. Every read-modify-write goes through here. */
+    async withLock(fn) {
+        await fs.mkdir(dirname(this.path), { recursive: true });
+        return withFileLock(this.lockPath, fn);
+    }
+    async saveLocked(input) {
+        const memories = await this.readAll();
+        const norm = input.text.trim().toLowerCase();
+        const existing = memories.find((m) => m.status === "active" && m.text.trim().toLowerCase() === norm);
+        if (existing)
+            return { action: "duplicate", memory: existing };
+        // Compute the semantic embedding once (best-effort). Stored on the record and reused
+        // for near-duplicate detection below. Undefined when no embedder is configured.
+        const embedding = await this.embed(input.text.trim());
+        const now = new Date().toISOString();
+        const memory = {
+            id: randomUUID(),
+            text: input.text.trim(),
+            type: input.type,
+            subject: input.subject?.trim().toLowerCase() || undefined,
+            source: input.source,
+            status: "active",
+            createdAt: now,
+            updatedAt: now,
+            // Assign a freshness window by type (RULES §2.5, §4). Undefined = never expires.
+            expiresAt: computeExpiresAt(input.type, now, this.ttl),
+            // Trusted provenance from the MCP handshake, not agent-claimed (D-024).
+            client: input.client,
+            // Local semantic vector (D-026); absent when embeddings are unavailable.
+            embedding,
+        };
+        let retired = [];
+        if (memory.subject) {
+            const matches = memories.filter((m) => m.status === "active" && m.subject === memory.subject);
+            if (matches.length > 0) {
+                const maxTrust = Math.max(...matches.map((m) => TRUST[m.source]));
+                if (TRUST[memory.source] < maxTrust) {
+                    // Lower-trust fact can't silently overwrite a higher-trust one → flag, don't store.
+                    return { action: "conflict", memory, conflictsWith: matches };
+                }
+                // Equal-or-higher trust + newer → supersede by recency (D-015).
+                retired = matches;
+                for (const old of retired) {
+                    old.status = "superseded";
+                    old.supersededBy = memory.id;
+                    old.supersededAt = now;
+                    old.updatedAt = now;
+                }
+            }
+        }
+        else if (embedding) {
+            // No subject to drive supersession, and this isn't an exact duplicate — check whether
+            // it is a SEMANTIC near-duplicate of something already on file (D-026). If so, don't
+            // store it; hand the existing record back so the agent decides (mirrors "conflict",
+            // never a silent drop). A subject-bearing save intentionally skips this: supplying a
+            // subject signals intent to update, handled by supersession above.
+            const near = this.findNearDuplicates(embedding, memories);
+            if (near.length > 0) {
+                return { action: "possible_duplicate", memory, possibleDuplicates: near };
+            }
+        }
+        memories.push(memory);
+        // Opportunistic compaction: drop long-dead records as part of this same write, so
+        // the file self-prunes without a background scheduler (Phase 2, item 2).
+        const next = this.dropCompactable(memories, Date.now());
+        await this.writeAll(next);
+        return retired.length > 0
+            ? { action: "superseded", memory, retired }
+            : { action: "created", memory };
+    }
+    /** Recall returns ACTIVE, unexpired memories only — retired/superseded and (soft-)
+     *  expired states are never surfaced as current facts (D-015: don't confront the user
+     *  with stale words). Pass `includeSuperseded` for the full audit history. */
+    async recall(query, limit = 5, includeSuperseded = false) {
+        const now = Date.now();
+        const memories = (await this.readAll()).filter((m) => includeSuperseded || (m.status === "active" && !isExpired(m.expiresAt, now)));
+        const q = query.trim();
+        if (!q)
+            return memories.slice(-limit).reverse();
+        // Fuzzy, deterministic lexical relevance (Phase 3, item 2). Always computed. Beats
+        // plain word-overlap on plurals/typos/word-boundary noise.
+        // When an embedder is available (D-026), also compute semantic similarity and blend it
+        // in — this is what earns synonym reach ("automobile" recalling a "car" memory) that
+        // the lexical scorer structurally cannot. A memory qualifies for recall if it is
+        // lexically relevant OR strongly semantically similar; results rank by the blended score.
+        const qVec = await this.embed(q);
+        const scored = memories.map((m) => {
+            const lexical = relevanceScore(q, m.text);
+            const semantic = qVec && Array.isArray(m.embedding) ? cosineSimilarity(qVec, m.embedding) : 0;
+            const qualifies = lexical >= MIN_RELEVANCE || semantic >= DEFAULT_SEMANTIC_MIN;
+            const score = qVec ? blendRelevance(lexical, semantic) : lexical;
+            return { m, score, qualifies };
+        });
+        return scored
+            .filter((x) => x.qualifies)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map((x) => x.m);
+    }
+    async forget(id) {
+        return this.withLock(async () => {
+            const memories = await this.readAll();
+            const next = memories.filter((m) => m.id !== id);
+            if (next.length === memories.length)
+                return false;
+            await this.writeAll(next);
+            return true;
+        });
+    }
+    /**
+     * Maintenance: physically remove records that have been expired for longer than the
+     * grace window (Phase 2, item 2). Soft-expired records (expired but still within
+     * grace) are deliberately kept — hidden from recall yet available for audit/recovery.
+     * Returns the number removed. Runs opportunistically on every save, and is also
+     * exposed here so a host can trigger it explicitly.
+     */
+    async compact() {
+        return this.withLock(async () => {
+            const memories = await this.readAll();
+            const next = this.dropCompactable(memories, Date.now());
+            const removed = memories.length - next.length;
+            if (removed > 0)
+                await this.writeAll(next);
+            return removed;
+        });
+    }
+    dropCompactable(memories, nowMs) {
+        return memories.filter((m) => !isCompactable(m.expiresAt, nowMs, this.graceMs));
+    }
+    /** Active memories whose embedding is at/above the near-duplicate threshold to `vec`,
+     *  most similar first. Records without an embedding (older/pre-embedding saves) are
+     *  simply skipped — they can't be compared, and we never guess a near-match (D-026). */
+    findNearDuplicates(vec, memories) {
+        return memories
+            .filter((m) => m.status === "active" && Array.isArray(m.embedding))
+            .map((m) => ({ memory: m, similarity: cosineSimilarity(vec, m.embedding) }))
+            .filter((x) => x.similarity >= this.dupThreshold)
+            .sort((a, b) => b.similarity - a.similarity);
+    }
+}

package/dist/store/lock.js

@@ -0,0 +1,92 @@
+// Cross-process advisory file lock (Phase 2, item 3).
+//
+// Two MCP server processes may share one store file (e.g. Claude Code and Cursor both
+// pointed at ~/.jamgate/memory.json). Without coordination, a read-modify-write in one
+// process can clobber a concurrent one (both read the same base, both write, last
+// rename wins → lost update). This lock serializes those writers.
+import { promises as fs } from "node:fs";
+// timeoutMs is aligned with staleMs on purpose: a waiter only gives up and proceeds
+// WITHOUT the lock once it has waited long enough that the holder's lock is itself stale
+// — and a stale lock is stolen (see the loop below) before the give-up branch is ever
+// reached. So under contention a live holder's write is never clobbered: a waiter either
+// acquires the lock or steals a provably-abandoned one. The give-up path survives only as
+// a last-resort liveness guard against pathological starvation.
+const DEFAULTS = { staleMs: 30_000, retryMs: 25, timeoutMs: 30_000 };
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Run `fn` while holding an exclusive on-disk lock at `lockPath`.
+ *
+ * Mechanism: create the lock file with the `wx` flag — `open(2)` with `O_CREAT|O_EXCL`,
+ * an atomic "create only if it does not exist". If creation fails with EEXIST the lock
+ * is held: wait and retry, unless the existing lock is older than `staleMs`, in which
+ * case we assume the holder died without releasing and steal it. On success we always
+ * remove the lock in a `finally`.
+ *
+ * WHAT THIS GUARANTEES: mutual exclusion between writers that (a) run on the same host,
+ * (b) share a real local filesystem, and (c) all go through this function. That is
+ * exactly the target case — several MCP server processes on one machine sharing one
+ * ~/.jamgate/memory.json. Combined with the caller's re-read-before-write (each holder
+ * loads the file fresh inside the lock), no committed write is lost.
+ *
+ * WHAT THIS DOES NOT GUARANTEE: it is not safe over NFS/SMB or other network
+ * filesystems, whose `O_EXCL` semantics are unreliable. Stale-lock stealing has an
+ * inherent small race: a holder stalled past `staleMs` could resume just as another
+ * process steals its lock. Acquisition has a `timeoutMs` after which we proceed WITHOUT
+ * the lock rather than fail the user's save; because `timeoutMs` defaults to `staleMs`,
+ * that give-up only comes due once the current lock is old enough to be stolen as stale
+ * — which happens first — so a live holder's write is not clobbered under contention. For
+ * the single-machine, local-disk MVP (D-010) this is sufficient; a hosted backend (D-019)
+ * would rely on its database's own transactions instead of a file lock.
+ */
+export async function withFileLock(lockPath, fn, options = {}) {
+    const { staleMs, retryMs, timeoutMs } = { ...DEFAULTS, ...options };
+    const deadline = Date.now() + timeoutMs;
+    let acquired = false;
+    for (;;) {
+        try {
+            const handle = await fs.open(lockPath, "wx");
+            await handle.writeFile(String(Date.now()), "utf8");
+            await handle.close();
+            acquired = true;
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            if (await isStale(lockPath, staleMs)) {
+                await fs.rm(lockPath, { force: true }); // steal an abandoned lock
+                continue;
+            }
+            if (Date.now() >= deadline)
+                break; // give up and proceed without the lock
+            await sleep(retryMs);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // Only remove the lock if we actually own it — never delete someone else's lock
+        // (which is what we would be doing had acquisition timed out).
+        if (acquired)
+            await fs.rm(lockPath, { force: true });
+    }
+}
+/** Is the lock file old enough to be presumed abandoned? Unreadable/garbage → stale. */
+async function isStale(lockPath, staleMs) {
+    try {
+        const raw = await fs.readFile(lockPath, "utf8");
+        const ts = Number(raw.trim());
+        if (!Number.isFinite(ts))
+            return true;
+        return Date.now() - ts > staleMs;
+    }
+    catch (err) {
+        // Vanished between EEXIST and now → not stale, just retry the create.
+        if (err.code === "ENOENT")
+            return false;
+        return false;
+    }
+}