jamgate 0.1.0

package/dist/store/schema.js

@@ -0,0 +1,43 @@
+// On-disk schema versioning + migration (Phase 2, item 4).
+//
+// The store file used to be a bare JSON array of memories with no version marker.
+// Adding fields (expiresAt) and, later, other shape changes means existing users'
+// files must keep working — so every file now carries an explicit `schemaVersion`, and
+// this module upgrades any older shape to the current one on read. Migration is pure
+// and in-memory; the upgraded shape is persisted the next time the store writes.
+import { computeExpiresAt } from "./ttl.js";
+/** Current on-disk schema version.
+ *  v1 (implicit): a bare `Memory[]`, no version field, no `expiresAt`.
+ *  v2: a versioned envelope `{ schemaVersion, memories }` with per-record `expiresAt`. */
+export const CURRENT_SCHEMA_VERSION = 2;
+/** Parse-and-migrate any recognized on-disk shape to the current in-memory envelope.
+ *  Unrecognized/empty input yields an empty store rather than throwing, so a corrupt or
+ *  blank file degrades to "no memories yet" instead of crashing the server on startup. */
+export function migrate(parsed, policy) {
+    // Legacy v1: a bare array of memories. Wrap it and backfill `expiresAt` so volatile
+    // records saved before Phase 2 start honoring their type's freshness window.
+    if (Array.isArray(parsed)) {
+        return {
+            schemaVersion: CURRENT_SCHEMA_VERSION,
+            memories: parsed.map((m) => backfillExpiry(m, policy)),
+        };
+    }
+    // v2+: already an envelope. Future migrations (v2→v3, …) branch on schemaVersion here.
+    if (parsed &&
+        typeof parsed === "object" &&
+        Array.isArray(parsed.memories)) {
+        return {
+            schemaVersion: CURRENT_SCHEMA_VERSION,
+            memories: parsed.memories,
+        };
+    }
+    return { schemaVersion: CURRENT_SCHEMA_VERSION, memories: [] };
+}
+/** Derive `expiresAt` for a legacy record that predates the expiry field. Records that
+ *  already have one, or that carry no type, are returned untouched. */
+function backfillExpiry(m, policy) {
+    if (m.expiresAt !== undefined || m.type === undefined)
+        return m;
+    const expiresAt = computeExpiresAt(m.type, m.createdAt, policy);
+    return expiresAt ? { ...m, expiresAt } : m;
+}

package/dist/store/ttl.js

@@ -0,0 +1,85 @@
+// Type-based TTL / expiry policy (Phase 2, item 2; RULES §2.5, §4).
+//
+// Every memory is a timestamped event with a freshness window, not a standing rule.
+// The window is derived from the memory's `type`, mirroring the 5-layer model in
+// RULES §4 (organized by how fast each layer changes):
+//
+//   identity   — who the user is (name, role, language) ............ never expires
+//   preference — lasting, identity-adjacent trait ................... never expires
+//   project    — what they're building (weeks–months) .............. long TTL
+//   state      — volatile focus / physical / emotional state ....... short TTL
+//
+// A memory with no `type` gets no expiry: we do not guess a lifespan for something we
+// could not classify — better to keep it than silently drop it.
+//
+// Every default is overridable via environment variables (see ENV_KEYS below), so a
+// deployment can tune freshness without code changes. This module is pure and holds no
+// I/O, which keeps the policy trivially testable.
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Default freshness windows, in days. `null` = never. Overridable per type via env. */
+export const DEFAULT_TTL_DAYS = {
+    identity: null,
+    preference: null,
+    project: 90,
+    state: 2,
+};
+/** How long (days) a soft-expired record is retained before compaction may drop it. */
+export const DEFAULT_COMPACT_GRACE_DAYS = 30;
+/** Env var that overrides each type's TTL. Value: a number of days, or `never`/`none`. */
+const ENV_KEYS = {
+    identity: "JAMGATE_TTL_IDENTITY_DAYS",
+    preference: "JAMGATE_TTL_PREFERENCE_DAYS",
+    project: "JAMGATE_TTL_PROJECT_DAYS",
+    state: "JAMGATE_TTL_STATE_DAYS",
+};
+/** Env var that overrides the compaction grace window (in days). */
+export const GRACE_ENV_KEY = "JAMGATE_COMPACT_GRACE_DAYS";
+/** Parse a days value into milliseconds. `never`/`none`/`off` → null; garbage → fallback. */
+function parseDaysMs(raw, fallbackMs) {
+    if (raw === undefined)
+        return fallbackMs;
+    const t = raw.trim().toLowerCase();
+    if (t === "never" || t === "none" || t === "off")
+        return null;
+    const n = Number(t);
+    if (!Number.isFinite(n) || n < 0)
+        return fallbackMs; // ignore junk, keep the default
+    return n * DAY_MS;
+}
+/** Resolve the effective TTL policy, applying any per-type env overrides. */
+export function resolveTtlPolicy(env = process.env) {
+    const policy = {};
+    for (const type of Object.keys(ENV_KEYS)) {
+        const def = DEFAULT_TTL_DAYS[type];
+        policy[type] = parseDaysMs(env[ENV_KEYS[type]], def === null ? null : def * DAY_MS);
+    }
+    return policy;
+}
+/** Resolve the compaction grace window, in milliseconds. Never falls back to null. */
+export function resolveGraceMs(env = process.env) {
+    const parsed = parseDaysMs(env[GRACE_ENV_KEY], DEFAULT_COMPACT_GRACE_DAYS * DAY_MS);
+    return parsed ?? DEFAULT_COMPACT_GRACE_DAYS * DAY_MS;
+}
+/** Compute the expiry timestamp for a memory of `type` created at `createdAtISO`.
+ *  Returns undefined for untyped or never-expiring types. */
+export function computeExpiresAt(type, createdAtISO, policy) {
+    if (!type)
+        return undefined;
+    const ttl = policy[type];
+    if (ttl === null || ttl === undefined)
+        return undefined;
+    return new Date(new Date(createdAtISO).getTime() + ttl).toISOString();
+}
+/** A memory is (soft-)expired once its expiry has passed. No expiry → never expires. */
+export function isExpired(expiresAt, nowMs) {
+    if (!expiresAt)
+        return false;
+    return new Date(expiresAt).getTime() <= nowMs;
+}
+/** A memory is compactable once it has been expired for longer than the grace window.
+ *  Soft-expired-but-within-grace records are kept (hidden from recall, still auditable). */
+export function isCompactable(expiresAt, nowMs, graceMs) {
+    if (!expiresAt)
+        return false;
+    return new Date(expiresAt).getTime() + graceMs <= nowMs;
+}

package/dist/store/types.js

@@ -0,0 +1,5 @@
+// The storage boundary for Jamgate (D-019).
+// The gate and the MCP server depend ONLY on the types and the `MemoryStore` interface
+// here — never on a concrete backend. That keeps storage swappable: the flat-file store
+// today, SQLite or a hosted Supabase store tomorrow, all behind the same contract.
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "jamgate",
+  "version": "0.1.0",
+  "mcpName": "io.github.amirj4m/jamgate",
+  "description": "A neutral, cross-agent memory quality gate for AI agents, delivered as an MCP server — a gate, not a store.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "ai-agents",
+    "quality-gate",
+    "claude",
+    "cursor",
+    "local-first",
+    "embeddings",
+    "llm"
+  ],
+  "license": "MIT",
+  "author": "jam",
+  "type": "module",
+  "homepage": "https://github.com/amirj4m/jamgate#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amirj4m/jamgate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amirj4m/jamgate/issues"
+  },
+  "bin": {
+    "jamgate": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "pretest": "tsc -p tsconfig.test.json",
+    "test": "node --test dist-test/test/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}