dsh-engram 0.2.0

package/lib/util.js

@@ -0,0 +1,119 @@
+/**
+ * dsh-engram: tiny shared utilities. Zero dependencies.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { basename, resolve } from "node:path";
+
+/** Random id for memories / tasks / links. */
+export function uuid() {
+  return randomUUID();
+}
+
+export const now = () => Date.now();
+
+/**
+ * Deterministic entity-node id from a name: `ent_<slug>` (lowercase, dashes),
+ * falling back to a short random id when the name slugs to nothing. esr_node
+ * uses it so re-calling with the same name updates the same node and esr_link
+ * can target it without a prior id lookup.
+ */
+export function slugId(name) {
+  const slug = String(name)
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return slug.length > 0 ? slug : shortId(uuid());
+}
+
+/** First 8 id chars as a short stable index marker (`#ab12cd34`). */
+export function shortId(id) {
+  const bare = String(id).replace(/[^a-z0-9]/gi, "");
+  return (bare.length >= 8 ? bare.slice(0, 8) : String(id).slice(0, 8)) || "?";
+}
+
+/** Truncate by Unicode code points (CJK-safe). */
+export function truncate(text, max) {
+  const chars = [...String(text)];
+  return chars.length <= max ? text : `${chars.slice(0, max).join("")}…`;
+}
+
+/** `MM-DD` from epoch millis — saves 3 chars per line vs full ISO. */
+export function fmtDate(ms) {
+  const d = new Date(ms);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/** Short content hash for exact-duplicate detection. */
+export function hashText(text) {
+  return createHash("sha256").update(String(text)).digest("hex").slice(0, 16);
+}
+
+/** Normalized workspace key: absolute, trailing separator removed, win32 case-folded. */
+export function workspaceKey(cwd) {
+  let key = resolve(cwd);
+  if (process.platform === "win32") key = key.toLowerCase();
+  return key.replace(/[\\/]+$/, "") || key;
+}
+
+/** Short human label for an index header. */
+export function label(cwd) {
+  return basename(cwd) || cwd;
+}
+
+/** Escape `<` the way DSH system sections do (XML-ish sanitization). */
+export function escapeLt(text) {
+  return String(text).replaceAll("<", "\\u003c");
+}
+
+/**
+ * CJK-aware tokenization: ASCII words plus CJK runs with overlapping bigrams.
+ * Deterministic, no model — the same vocabulary used for recall scoring and
+ * auto-capture dedup.
+ */
+export function tokenize(input) {
+  const tokens = new Set();
+  for (const word of String(input).toLowerCase().split(/\s+/)) {
+    if (word.length === 0) continue;
+    const runs = word.match(/[\u3400-\u9fff]+|[^\u3400-\u9fff]+/g) ?? [];
+    for (const run of runs) {
+      if (/^[\u3400-\u9fff]+$/.test(run)) {
+        if (run.length >= 2) {
+          for (let i = 0; i < run.length - 1; i += 1) tokens.add(run.slice(i, i + 2));
+        }
+      } else {
+        for (const token of run.split(/[^a-z0-9]+/)) {
+          if (token.length > 0) tokens.add(token);
+        }
+      }
+    }
+  }
+  return [...tokens];
+}
+
+/**
+ * Deterministic 3-tier scoring over one record's text + tags:
+ * exact tag match (3) > case-insensitive text substring (2) > fuzzy tag overlap (1),
+ * plus a phrase boost (4) for multi-word queries. Mirrors the proven
+ * dsh-native-memory scoring model.
+ */
+export function scoreRecord(record, tokens, fullQuery, phraseBoost) {
+  const text = String(record.text).toLowerCase();
+  const tags = (record.tags ?? []).map((t) => String(t).toLowerCase());
+  let score = 0;
+  for (const token of tokens) {
+    if (tags.includes(token)) score += 3;
+    else if (tags.some((tag) => tag.includes(token) || token.includes(tag))) score += 1;
+    if (text.includes(token)) score += 2;
+  }
+  if (phraseBoost && fullQuery.length > 1 && text.includes(fullQuery)) score += 4;
+  return score;
+}
+
+/** Newest first, then id ascending (deterministic). */
+export function byRecency(left, right) {
+  return (right.updatedAt ?? 0) - (left.updatedAt ?? 0) || String(left.id).localeCompare(String(right.id));
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "dsh-engram",
+  "description": "Minimalist long-term memory for DeepSeek Harness, distilling symbolic-index + pi-esr ideas: zero-LLM auto-capture, a symbolic [ENGRAM] index with progressive disclosure, and an ESR-lite evidence-closure protocol (esr_task / esr_node / esr_close / esr_link). Real agent-behaviour telemetry (usage rollup + /stats) and a deterministic offline recall benchmark (npm run eval). Hot path is model-free; storage on ctx.storageDomain; web memory viewer, observability panel and config card through DSH's native settings slots.",
+  "version": "0.2.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skepsun/dsh-engram.git"
+  },
+  "homepage": "https://github.com/skepsun/dsh-engram",
+  "bugs": {
+    "url": "https://github.com/skepsun/dsh-engram/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "setup": "node scripts/setup-links.mjs",
+    "prepublishOnly": "node scripts/prepublish-check.mjs",
+    "build:client": "node client/build.mjs",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "eval": "node eval/recall-bench.mjs",
+    "typecheck": "echo ok"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-storage-domain": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "memory",
+    "long-term-memory",
+    "symbolic-index",
+    "pi-esr"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}