midas-memory-mcp 0.0.3

package/README.md

@@ -0,0 +1,65 @@
+# midas-memory-mcp (TypeScript) — experimental
+
+A TypeScript port of [Midas](https://github.com/vornicx/Midas): local-first, source-traceable
+memory for AI agents over MCP — **no LLM and no network at ingest or query**.
+
+> **Status: experimental.** The Python server (`pip install "midas-memory[mcp,local]"`) is the
+> reference implementation with semantic ONNX embeddings, NLI-gated belief revision, and the full
+> eval harness behind it. This port covers the core for Node-first setups.
+
+## Why it exists
+
+Most MCP clients live in the Node ecosystem. This package gives them a zero-Python install:
+
+```bash
+npx midas-memory-mcp        # or: npm i -g midas-memory-mcp && midas-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "midas": {
+      "command": "npx",
+      "args": ["-y", "midas-memory-mcp"],
+      "env": { "MIDAS_MCP_DB": "/home/you/.midas/memory.sqlite3" }
+    }
+  }
+}
+```
+
+## Parity with the Python server
+
+- **Same SQLite schema and float32 blob encoding** — a TS server and a Python server can point at
+  the **same DB file** and share one live memory (both probe SQLite's `data_version` and refresh
+  on other connections' writes). Verified bidirectionally in tests.
+- **Bit-comparable hashing embedder** (md5 token hashing, identical sign/index math) — vectors
+  written by one runtime are recalled semantically by the other. Parity is pinned by a fixture
+  generated from the Python implementation.
+- **Same tool surface** — `remember`, `capture` (policy-gated, no LLM), `recall`
+  (source-traceable), `build_context` (lean dated lines + "Today is" anchor), `inspect_memory`,
+  `check_memory_use` (provenance guard), `forget`, `forget_matching` (dry-run + audit),
+  `forget_all`, `maintain`, `stats`, `memory_policy` — plus the same env knobs
+  (`MIDAS_MCP_DB`, `MIDAS_MCP_MAX_RECORDS`, `MIDAS_MCP_MIN_IMPORTANCE`, `MIDAS_MCP_NAMESPACE`,
+  `MIDAS_MCP_ACTOR`, `MIDAS_MCP_SUPERSEDE`) and the same injected agent policy text.
+- **Same shipping behaviour** — relevance × importance × recency ranking, the measured-safe
+  scale-free parsimony floor (`minRelevanceRatio` 0.3), BM25+RRF hybrid (cached index), typed
+  belief revision with supersession chains, no-LLM importance scoring, selective forgetting with
+  durable-tier protection.
+
+## Not ported (yet)
+
+- **Semantic ONNX embeddings** (bge / multilingual) — the default embedder here is the offline
+  hashing one (lexical-ish). For real semantic recall today, run the Python server; both can share
+  the same DB.
+- Local NLI contradiction gating, the cross-encoder reranker, and the eval harness.
+
+## Requirements
+
+Node **>= 22.5** (uses the built-in `node:sqlite`; you may see its experimental warning on stderr).
+
+```bash
+npm test   # builds + runs the suite, including the Python-parity fixture
+```
+
+MIT — same license, same repo, same [PRIVACY.md](../../PRIVACY.md) posture: everything stays on
+your machine.

package/dist/bin/midas-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/midas-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "../mcp.js";
+main().catch((err) => {
+    console.error("[midas-mcp-ts] fatal:", err);
+    process.exit(1);
+});

package/dist/bm25.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryRecord } from "./types.js";
+export declare class BM25 {
+    private readonly records;
+    private readonly dls;
+    private readonly postings;
+    private readonly idf;
+    private readonly avgdl;
+    constructor(records: MemoryRecord[]);
+    /** Map record id -> BM25 score (only positive scores included). */
+    scores(query: string): Map<string, number>;
+}

package/dist/bm25.js

@@ -0,0 +1,55 @@
+/** BM25 lexical ranking — port of `midas/bm25.py` (Okapi BM25, non-negative IDF, per-term
+ * posting lists so a query touches only documents sharing a term with it). */
+import { tokenize } from "./embeddings.js";
+const K1 = 1.5;
+const B = 0.75;
+export class BM25 {
+    records;
+    dls = [];
+    postings = new Map();
+    idf = new Map();
+    avgdl;
+    constructor(records) {
+        this.records = records;
+        for (let i = 0; i < records.length; i++) {
+            const doc = tokenize(records[i].content);
+            this.dls.push(doc.length);
+            const tf = new Map();
+            for (const t of doc)
+                tf.set(t, (tf.get(t) ?? 0) + 1);
+            for (const [term, f] of tf) {
+                let list = this.postings.get(term);
+                if (!list)
+                    this.postings.set(term, (list = []));
+                list.push([i, f]);
+            }
+        }
+        this.avgdl = this.dls.length ? this.dls.reduce((a, b) => a + b, 0) / this.dls.length : 0;
+        const n = records.length;
+        for (const [t, p] of this.postings) {
+            this.idf.set(t, Math.log(1 + (n - p.length + 0.5) / (p.length + 0.5)));
+        }
+    }
+    /** Map record id -> BM25 score (only positive scores included). */
+    scores(query) {
+        const qTerms = tokenize(query);
+        const avgdl = this.avgdl || 1.0;
+        const byDoc = new Map();
+        for (const term of qTerms) {
+            const postings = this.postings.get(term);
+            if (!postings)
+                continue;
+            const idf = this.idf.get(term);
+            for (const [i, f] of postings) {
+                const dl = this.dls[i];
+                const s = (byDoc.get(i) ?? 0) + (idf * (f * (K1 + 1))) / (f + K1 * (1 - B + (B * dl) / avgdl));
+                byDoc.set(i, s);
+            }
+        }
+        const out = new Map();
+        for (const [i, s] of byDoc)
+            if (s > 0)
+                out.set(this.records[i].id, s);
+        return out;
+    }
+}

package/dist/embeddings.d.ts

@@ -0,0 +1,14 @@
+export declare function tokenize(text: string): string[];
+export interface Embedder {
+    dim: number;
+    embed(text: string): Float32Array;
+    embedMany(texts: string[]): Float32Array[];
+}
+export declare function l2Normalize(vec: Float32Array): Float32Array;
+export declare function cosine(a: Float32Array, b: Float32Array): number;
+export declare class HashingEmbedder implements Embedder {
+    readonly dim: number;
+    constructor(dim?: number);
+    embed(text: string): Float32Array;
+    embedMany(texts: string[]): Float32Array[];
+}

package/dist/embeddings.js

@@ -0,0 +1,62 @@
+/** Embeddings — the offline `HashingEmbedder` is a byte-for-byte port of the Python one
+ * (same md5 token hashing, same sign/index math), so a TypeScript process produces the SAME
+ * vectors as a Python process and both can share one on-disk store semantically.
+ * A local ONNX semantic embedder (bge / multilingual) is the planned next step. */
+import { createHash } from "node:crypto";
+const WORD = /[\p{L}\p{N}_]+/gu;
+export function tokenize(text) {
+    const out = [];
+    for (const m of text.toLowerCase().matchAll(WORD)) {
+        if (m[0].length > 2)
+            out.push(m[0]);
+    }
+    return out;
+}
+export function l2Normalize(vec) {
+    let norm = 0;
+    for (const v of vec)
+        norm += v * v;
+    norm = Math.sqrt(norm);
+    if (norm === 0)
+        return vec;
+    const out = new Float32Array(vec.length);
+    for (let i = 0; i < vec.length; i++)
+        out[i] = vec[i] / norm;
+    return out;
+}
+export function cosine(a, b) {
+    let s = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++)
+        s += a[i] * b[i];
+    return s;
+}
+export class HashingEmbedder {
+    dim;
+    constructor(dim = 256) {
+        this.dim = dim;
+    }
+    embed(text) {
+        const vec = new Float64Array(this.dim);
+        for (const tok of tokenize(text)) {
+            const digest = createHash("md5").update(tok, "utf8").digest();
+            const h = digest.readBigUInt64BE(0); // == Python int.from_bytes(digest[:8], "big")
+            const idx = Number(h % BigInt(this.dim));
+            const sign = (h >> 8n) & 1n ? 1.0 : -1.0;
+            vec[idx] += sign;
+        }
+        // Normalize in float64 BEFORE casting to float32 — the same order Python uses, so the two
+        // implementations produce bit-comparable vectors.
+        let norm = 0;
+        for (const v of vec)
+            norm += v * v;
+        norm = Math.sqrt(norm);
+        if (norm > 0)
+            for (let i = 0; i < vec.length; i++)
+                vec[i] /= norm;
+        return Float32Array.from(vec);
+    }
+    embedMany(texts) {
+        return texts.map((t) => this.embed(t));
+    }
+}

package/dist/guard.d.ts

@@ -0,0 +1,17 @@
+/** Provenance guard — port of `midas/guard.py`'s decision core: low-trust memory may guide
+ * planning, but external/destructive actions require explicit user confirmation. */
+import type { MemoryRecord } from "./types.js";
+export type MemoryUse = "planning" | "answer" | "external_action" | "destructive_action";
+export declare const MEMORY_USES: readonly MemoryUse[];
+export interface GuardDecision {
+    allowed: boolean;
+    intended_use: MemoryUse;
+    acting_agent: string | null;
+    allowed_ids: string[];
+    blocked_ids: string[];
+    reason: string;
+}
+export declare function decideMemoryUse(records: MemoryRecord[], opts?: {
+    intendedUse?: MemoryUse;
+    actingAgent?: string | null;
+}): GuardDecision;

package/dist/guard.js

@@ -0,0 +1,37 @@
+import { MEMORY_PROVENANCE } from "./types.js";
+export const MEMORY_USES = [
+    "planning",
+    "answer",
+    "external_action",
+    "destructive_action",
+];
+const ALLOWED_BY_USE = {
+    planning: MEMORY_PROVENANCE,
+    answer: ["action", "observation", "user_confirmation"],
+    external_action: ["user_confirmation"],
+    destructive_action: ["user_confirmation"],
+};
+export function decideMemoryUse(records, opts = {}) {
+    const use = opts.intendedUse ?? "planning";
+    const allowedProv = ALLOWED_BY_USE[use];
+    if (!allowedProv)
+        throw new Error(`invalid memory use '${use}'`);
+    const allowedIds = [];
+    const blockedIds = [];
+    for (const r of records) {
+        (allowedProv.includes(r.provenance) ? allowedIds : blockedIds).push(r.id);
+    }
+    const allowed = allowedIds.length > 0;
+    const reason = allowed
+        ? `allowed: ${allowedIds.length} memory(ies) satisfy provenance for ${use}`
+        : `blocked: ${use} requires provenance in [${allowedProv.join(", ")}]; ` +
+            "ask the user to confirm in the current turn";
+    return {
+        allowed,
+        intended_use: use,
+        acting_agent: opts.actingAgent ?? null,
+        allowed_ids: allowedIds,
+        blocked_ids: blockedIds,
+        reason,
+    };
+}

package/dist/importance.d.ts

@@ -0,0 +1,6 @@
+/** No-LLM per-turn importance scoring — a faithful port of `midas/importance.py`.
+ * ContentImportance: content-word density + specifics (digits, proper-noun-likes) with an
+ * anti-backchannel floor. StructuralImportance adds assertion-vs-question structure. */
+export type ImportanceScorer = (text: string) => number;
+export declare function contentImportance(text: string): number;
+export declare function structuralImportance(text: string): number;

package/dist/importance.js

@@ -0,0 +1,81 @@
+/** No-LLM per-turn importance scoring — a faithful port of `midas/importance.py`.
+ * ContentImportance: content-word density + specifics (digits, proper-noun-likes) with an
+ * anti-backchannel floor. StructuralImportance adds assertion-vs-question structure. */
+const STOP = new Set([
+    "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for", "of", "with", "by", "is",
+    "are", "was", "were", "be", "been", "being", "have", "has", "had", "do", "does", "did", "will",
+    "would", "could", "should", "may", "might", "must", "can", "we", "our", "us", "it", "its", "this",
+    "that", "these", "those", "i", "you", "he", "she", "they", "them", "my", "your", "his", "her",
+    "their", "me", "him", "so", "just", "yeah", "yes", "no", "ok", "okay", "haha", "lol", "hey", "hi",
+    "oh", "well", "really", "very", "too", "also", "then", "than", "as", "if", "not", "what", "when",
+    "how", "why", "who", "about", "from", "up", "out", "get", "got", "like", "good", "nice", "cool",
+    "thanks", "thank", "please", "sure",
+]);
+const WORD = /^[A-Za-z][A-Za-z'-]*$/;
+const HAS_DIGIT = /\d/;
+const SENT_END = /[.!?]$/;
+const PUNCT = /^[.,;:!?"'()[\]]+|[.,;:!?"'()[\]]+$/g;
+export function contentImportance(text) {
+    text = (text ?? "").trim();
+    if (!text)
+        return 1;
+    const tokens = text.split(/\s+/);
+    const content = new Set();
+    for (const w of tokens) {
+        const core = w.replace(PUNCT, "");
+        if (WORD.test(core) && core.length > 3 && !STOP.has(core.toLowerCase())) {
+            content.add(core.toLowerCase());
+        }
+    }
+    const nContent = content.size;
+    const nDigit = tokens.filter((w) => HAS_DIGIT.test(w)).length;
+    let nProper = 0;
+    let prevEndsSentence = true;
+    for (const w of tokens) {
+        const core = w.replace(PUNCT, "");
+        if (!prevEndsSentence &&
+            core.length > 2 &&
+            core[0] >= "A" &&
+            core[0] <= "Z" &&
+            /^[A-Za-z]+$/.test(core) &&
+            !STOP.has(core.toLowerCase())) {
+            nProper += 1;
+        }
+        prevEndsSentence = SENT_END.test(w);
+    }
+    if (tokens.length <= 4 && nDigit === 0 && nProper === 0 && nContent <= 1)
+        return 1;
+    let score = 1;
+    if (nContent >= 3)
+        score += 1;
+    if (nContent >= 7)
+        score += 1;
+    if (nDigit >= 1)
+        score += 1;
+    if (nProper >= 1)
+        score += 1;
+    return Math.max(1, Math.min(5, score));
+}
+const FIRST_PERSON = /\b(i'?m|i\s+am|my|mine|i\s+have|i'?ve|i\s+(?:prefer|like|love|hate|need|use|own|drive|speak|work|live)|i\s+was\s+born)\b/i;
+const DURABLE = /\b(prefer|allergic|favou?rite|deadline|due|born|named|called|decided|always|never|must|require|policy|rule)\b/i;
+const COPULA = /\b(is|are|was|were|named|called)\b/i;
+const META = /\b(let'?s|let\s+me|can\s+you|could\s+you|should\s+we|shall\s+we|please|thanks|thank\s+you|sounds?\s+good|got\s+it|no\s+problem)\b/i;
+export function structuralImportance(text) {
+    text = (text ?? "").trim();
+    const base = contentImportance(text);
+    const isQuestion = text.endsWith("?");
+    let boost = 0;
+    if (FIRST_PERSON.test(text))
+        boost += 1;
+    if (DURABLE.test(text))
+        boost += 1;
+    if (!isQuestion && COPULA.test(text))
+        boost += 1;
+    let penalty = 0;
+    if (isQuestion)
+        penalty += 1;
+    else if (boost === 0 && META.test(text))
+        penalty += 1;
+    const score = base + Math.min(boost, 2) - penalty;
+    return Math.max(1, Math.min(5, score));
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { HashingEmbedder, cosine, l2Normalize, tokenize, type Embedder } from "./embeddings.js";
+export { contentImportance, structuralImportance, type ImportanceScorer } from "./importance.js";
+export { BM25 } from "./bm25.js";
+export { InMemoryStore, SQLiteStore, type Predicate } from "./store.js";
+export { Memory, DEFAULT_POLICY, DURABLE_KINDS, approxTokens, formatRecord, type CaptureResult, type ContextBlock, type MemoryOptions, type MemoryPolicy, type RecallOptions, type RememberOptions, } from "./memory.js";
+export { AGENT_MEMORY_INSTRUCTIONS, policySummary } from "./policy.js";
+export { decideMemoryUse, MEMORY_USES, type GuardDecision, type MemoryUse } from "./guard.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { HashingEmbedder, cosine, l2Normalize, tokenize } from "./embeddings.js";
+export { contentImportance, structuralImportance } from "./importance.js";
+export { BM25 } from "./bm25.js";
+export { InMemoryStore, SQLiteStore } from "./store.js";
+export { Memory, DEFAULT_POLICY, DURABLE_KINDS, approxTokens, formatRecord, } from "./memory.js";
+export { AGENT_MEMORY_INSTRUCTIONS, policySummary } from "./policy.js";
+export { decideMemoryUse, MEMORY_USES } from "./guard.js";

package/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+/** Midas as an MCP server (TypeScript) — same tool surface, env knobs, injected policy, and
+ * SQLite schema as the Python `midas.mcp_server`, so the two are interchangeable and can even
+ * share one DB file live. No LLM and no network at ingest/query (hashing embedder; a local ONNX
+ * semantic embedder is the planned next step — use the Python server when you need bge today). */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;
+export declare function main(): Promise<void>;