@justfortytwo/memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enrico Deleo
+
+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,183 @@
+# @justfortytwo/memory
+
+A standalone **semantic-memory MCP server**. It stores text "memories" with
+free-form provenance and recalls them by meaning (vector search), by keyword
+(FTS5), or by structured filter. Backed by SQLite + [`sqlite-vec`], embeddings
+from a local [Ollama] model.
+
+It is **persona-agnostic**: no journal/persona/approval coupling, just a generic
+memory store and tool surface. It can be used on its own, or as a Claude Code
+plugin.
+
+[`sqlite-vec`]: https://github.com/asg017/sqlite-vec
+[Ollama]: https://ollama.com
+
+## What it stores
+
+A memory is `content` plus provenance:
+
+| field | meaning |
+|-------|---------|
+| `content` | the text (embedded for recall) |
+| `source` | where it came from — free-form (`owner`, `web`, `tool:foo`) |
+| `observed` | how it was observed — free-form (`stated`, `inferred`, `imported`) |
+| `date` | ISO date the memory pertains to (defaults to today, UTC) |
+| `tags` | free-form tags for filtering |
+| `supersedes` | id of a prior memory this one replaces (history is **kept**) |
+
+Recall is hybrid: `recall` (semantic), `lexical` (FTS5 keyword), and `query`
+(structured). `reindex` + `recall_docs` index/search a directory of markdown
+documents separately from the memory store.
+
+## MCP tools
+
+The server registers under the id **`fortytwo-memory`**, so a consumer calls the
+tools as `mcp__fortytwo-memory__<tool>`:
+
+| tool | description |
+|------|-------------|
+| `store` | store a memory (+ provenance); set `supersedes` to replace one |
+| `query` | structured query (source/observed/tag/time; live rows by default) |
+| `recall` | semantic top-k recall by meaning |
+| `recall_docs` | semantic recall over reindexed markdown |
+| `lexical` | full-text keyword search (FTS5) |
+| `reindex` | self-heal the doc index from a markdown directory |
+| `export_range` | render a date range of memories to markdown |
+
+### Contract version
+
+Consumers depend on the **tool surface**, not the internals. The contract is
+versioned:
+
+```ts
+import { MEMORY_TOOL_CONTRACT_VERSION, memoryToolContract } from '@justfortytwo/memory/contract';
+```
+
+- A **major** change to a tool name, its required inputs, or its result shape is
+  a **contract break** → bump `MEMORY_TOOL_CONTRACT_VERSION`. Siblings pin a
+  caret range on `@justfortytwo/memory`, so a major bump forces an explicit
+  opt-in.
+- Additive changes (new optional inputs, new tools) do **not** bump it.
+
+`memoryToolContract` is the authoritative human-readable list of tools and their
+guarantees, kept in sync with the wire schema in `src/tools.ts`.
+
+## Embedder
+
+The default embedder is **`OllamaEmbedder`**, which calls a local Ollama
+`/api/embeddings` endpoint.
+
+```bash
+OLLAMA_BASE_URL=http://localhost:11434   # default
+EMBED_MODEL=qwen3-embedding:0.6b         # default model (1024-dim)
+```
+
+Pull the model once:
+
+```bash
+ollama pull qwen3-embedding:0.6b
+```
+
+If `EMBED_MODEL` is **unset**, the server falls back to a deterministic,
+dependency-free **`FakeEmbedder`** — useful for tests, CI, and first-run smoke
+checks with zero infra. (The vector tables are fixed at 1024-dim; a model with a
+different dimensionality requires a schema change.)
+
+## Standalone usage
+
+```bash
+# build (once); the server runs the built JS, not TS
+npm run build
+
+# apply migrations to the DB (DB_PATH or ./memory.db)
+DB_PATH=./memory.db npm run migrate
+
+# run the MCP server over stdio
+DB_PATH=./memory.db EMBED_MODEL=qwen3-embedding:0.6b fortytwo-memory
+```
+
+The `bin` is `fortytwo-memory` → `dist/index.js`. You can also `npx -y
+@justfortytwo/memory` once published.
+
+### As a library
+
+```ts
+import { openDb, runMigrations, OllamaEmbedder, store, recall } from '@justfortytwo/memory';
+
+const h = openDb('memory.db');
+await runMigrations(h.k);
+const embedder = new OllamaEmbedder();
+
+await store(h, embedder, { content: 'the deploy script lives in scripts/deploy.sh', source: 'owner', observed: 'stated' });
+const hits = await recall(h, embedder, 'how do I deploy?', 5);
+```
+
+## As a Claude Code plugin
+
+`.claude-plugin/plugin.json` declares the plugin; `.mcp.json` registers the
+`fortytwo-memory` server. By default it launches via `npx`:
+
+```jsonc
+{
+  "mcpServers": {
+    "fortytwo-memory": {
+      "command": "npx",
+      "args": ["-y", "@justfortytwo/memory"],
+      "env": {
+        "OLLAMA_BASE_URL": "http://localhost:11434",
+        "EMBED_MODEL": "qwen3-embedding:0.6b",
+        "DB_PATH": "${CLAUDE_PLUGIN_DATA}/memory.db"
+      }
+    }
+  }
+}
+```
+
+`${CLAUDE_PLUGIN_DATA}` survives plugin updates, so the DB persists across
+upgrades. When developing from source, build first (`npm run build`) and swap
+the command to `node` with args `["${CLAUDE_PLUGIN_ROOT}/dist/index.js"]`.
+Claude Code does **not** build MCP servers — they run via npm/npx.
+
+## Continuous enrichment
+
+`enrich(h, embedder, candidates)` folds a batch of candidate memories into the
+store: it drops low-salience candidates, **dedupes** near-duplicates by meaning,
+and writes the survivors with provenance — honoring an explicit `supersedes` to
+replace a stale belief (history is kept, never a silent overwrite).
+`enrichFromTurn(h, embedder, turn, extractor)` runs an injected `SalienceExtractor`
+and feeds its candidates to `enrich`.
+
+The salience extractor itself is model-driven and lives in the sibling
+**`@justfortytwo/salience`** engine (a `SalienceExtractor` with an injected
+`LlmClient`) — memory owns only the dedupe + write, never the model call.
+
+## Peer seams
+
+memory depends on two sibling packages **one-directionally** (declared as optional
+peers, no cycle):
+
+- **`@justfortytwo/gate`** — memory ships `GateApprovalStore`
+  (`src/gate-approval-store.ts`), a durable SQLite-backed implementation of
+  gate's `ApprovalStore` + `AuditLogger` interfaces. Pass it to gate's
+  `decide(..., { store, audit })` to back the safety gate's one-shot approvals
+  with memory's db instead of the gate's standalone JSONL store.
+- **`@justfortytwo/salience`** — the model-driven salience extractor injected
+  into `enrichFromTurn` (see above).
+
+## Development
+
+```bash
+npm run build      # tsc
+npm test           # vitest run
+npm run test:watch # vitest
+```
+
+Set `RUN_OLLAMA_TESTS=1` to run the opt-in live-Ollama embedder test.
+
+## License
+
+MIT © 2026 Enrico Deleo
+
+---
+
+Created and maintained by [**Enrico Deleo**](https://enricodeleo.com).

package/dist/contract.d.ts

@@ -0,0 +1,19 @@
+/** Bump on any breaking change to the tool surface below. */
+export declare const MEMORY_TOOL_CONTRACT_VERSION = 1;
+/** The MCP server id under which these tools are registered. */
+export declare const MEMORY_SERVER_ID = "fortytwo-memory";
+/** Fully-qualified MCP tool names a consumer invokes. */
+export declare const MEMORY_MCP_TOOLS: readonly ["mcp__fortytwo-memory__store", "mcp__fortytwo-memory__query", "mcp__fortytwo-memory__recall", "mcp__fortytwo-memory__recall_docs", "mcp__fortytwo-memory__lexical", "mcp__fortytwo-memory__reindex", "mcp__fortytwo-memory__export_range"];
+export type MemoryMcpTool = (typeof MEMORY_MCP_TOOLS)[number];
+/** Bare tool names (server-local, without the mcp__<server>__ prefix). */
+export interface MemoryToolSpec {
+    /** Bare tool name as declared in the MCP ListTools response. */
+    name: string;
+    /** One-line human description of the tool's contract. */
+    summary: string;
+}
+/**
+ * Documented contract for each tool. Kept in sync with tools.ts (the wire
+ * schema). This is the authoritative human-readable list siblings code against.
+ */
+export declare const memoryToolContract: readonly MemoryToolSpec[];

package/dist/contract.js

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// Cross-package contract for @justfortytwo/memory.
+//
+// Siblings depend on this server through a STABLE tool surface, not its
+// internals. The contract version is the coordination point:
+//   - A MAJOR bump (breaking change to a tool name, its required inputs, or its
+//     result shape) is a CONTRACT BREAK. Siblings pin a caret range on
+//     @justfortytwo/memory; a major bump forces them to opt in.
+//   - Additive changes (new optional inputs, new tools) do NOT bump the version.
+//
+// The MCP tools are namespaced by the registered server id "fortytwo-memory"
+// (see .mcp.json), so a consumer calls them as `mcp__fortytwo-memory__<tool>`.
+// ---------------------------------------------------------------------------
+/** Bump on any breaking change to the tool surface below. */
+export const MEMORY_TOOL_CONTRACT_VERSION = 1;
+/** The MCP server id under which these tools are registered. */
+export const MEMORY_SERVER_ID = 'fortytwo-memory';
+/** Fully-qualified MCP tool names a consumer invokes. */
+export const MEMORY_MCP_TOOLS = [
+    'mcp__fortytwo-memory__store',
+    'mcp__fortytwo-memory__query',
+    'mcp__fortytwo-memory__recall',
+    'mcp__fortytwo-memory__recall_docs',
+    'mcp__fortytwo-memory__lexical',
+    'mcp__fortytwo-memory__reindex',
+    'mcp__fortytwo-memory__export_range',
+];
+/**
+ * Documented contract for each tool. Kept in sync with tools.ts (the wire
+ * schema). This is the authoritative human-readable list siblings code against.
+ */
+export const memoryToolContract = [
+    { name: 'store', summary: 'Store a memory (content + free-form provenance) and embed it for recall. Supports SUPERSEDE.' },
+    { name: 'query', summary: 'Structured query over the memory store (source/observed/tag/time, live-only by default).' },
+    { name: 'recall', summary: 'Semantic top-k recall over the memory store by meaning.' },
+    { name: 'recall_docs', summary: 'Semantic top-k recall over reindexed markdown documents (the doc_vec index).' },
+    { name: 'lexical', summary: 'Full-text keyword search over the memory store (FTS5).' },
+    { name: 'reindex', summary: 'Self-heal the doc recall index from a directory of markdown files.' },
+    { name: 'export_range', summary: 'Render a date range of memories to markdown (for debugging/export).' },
+];
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mDAAmD;AACnD,EAAE;AACF,wEAAwE;AACxE,6DAA6D;AAC7D,gFAAgF;AAChF,uEAAuE;AACvE,gEAAgE;AAChE,iFAAiF;AACjF,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAE9E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAElD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,6BAA6B;IAC7B,6BAA6B;IAC7B,8BAA8B;IAC9B,mCAAmC;IACnC,+BAA+B;IAC/B,+BAA+B;IAC/B,oCAAoC;CAC5B,CAAC;AAYX;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA8B;IAC3D,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,8FAA8F,EAAE;IAC1H,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,0FAA0F,EAAE;IACtH,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,yDAAyD,EAAE;IACtF,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,8EAA8E,EAAE;IAChH,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,wDAAwD,EAAE;IACtF,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,oEAAoE,EAAE;IAClG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,qEAAqE,EAAE;CAChG,CAAC"}

package/dist/db.d.ts

@@ -0,0 +1,11 @@
+import Database from 'better-sqlite3';
+import { type Knex } from 'knex';
+/** Embedding dimensionality. qwen3-embedding:0.6b emits 1024-dim vectors. */
+export declare const EMBED_DIM = 1024;
+export interface DbHandles {
+    /** Raw handle: sqlite-vec + FTS5 ops, and atomic relational+vector writes. */
+    raw: Database.Database;
+    /** Knex handle: migrations + portable relational reads/writes. */
+    k: Knex;
+}
+export declare function openDb(dbPath: string): DbHandles;

package/dist/db.js

@@ -0,0 +1,33 @@
+import Database from 'better-sqlite3';
+import knexPkg from 'knex';
+import * as sqliteVec from 'sqlite-vec';
+// knex ships as CommonJS; under NodeNext ESM (`node dist/index.js`) a named
+// import `{ knex }` throws "Named export 'knex' not found". Default-import the
+// namespace and destructure — identical binding, ESM-safe. (vitest interops the
+// named form fine, which is why db.test passes but the raw-node server did not.)
+const { knex } = knexPkg;
+/** Embedding dimensionality. qwen3-embedding:0.6b emits 1024-dim vectors. */
+export const EMBED_DIM = 1024;
+export function openDb(dbPath) {
+    const raw = new Database(dbPath);
+    raw.pragma('journal_mode = WAL');
+    raw.pragma('busy_timeout = 5000'); // wait up to 5s on writer contention
+    sqliteVec.load(raw); // registers the vec0 module + scalar helpers
+    // vec0 tables live on the raw handle: sqlite-vec is loaded here, NOT on Knex's
+    // own connection, so Knex migrations cannot create vec0 tables. (FTS5, which is
+    // compiled into SQLite, and the relational schema CAN be Knex migrations.)
+    //
+    // `memory_vec` indexes the generic memory store; `doc_vec` indexes reindexed
+    // markdown documents. (Generic rename of the original assistant's `journal_vec`.)
+    const ddl = (sql) => raw.exec(sql);
+    ddl(`CREATE VIRTUAL TABLE IF NOT EXISTS memory_vec USING vec0(embedding float[${EMBED_DIM}])`);
+    ddl(`CREATE VIRTUAL TABLE IF NOT EXISTS doc_vec USING vec0(embedding float[${EMBED_DIM}])`);
+    const k = knex({
+        client: 'better-sqlite3',
+        connection: { filename: dbPath },
+        useNullAsDefault: true,
+        pool: { min: 1, max: 1 },
+    });
+    return { raw, k };
+}
+//# sourceMappingURL=db.js.map

package/dist/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,OAAsB,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,SAAS,MAAM,YAAY,CAAC;AAExC,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;AAEzB,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;AAS9B,MAAM,UAAU,MAAM,CAAC,MAAc;IACnC,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,GAAG,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACjC,GAAG,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAAC,qCAAqC;IACxE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,6CAA6C;IAElE,+EAA+E;IAC/E,gFAAgF;IAChF,2EAA2E;IAC3E,EAAE;IACF,6EAA6E;IAC7E,kFAAkF;IAClF,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,GAAG,CAAC,4EAA4E,SAAS,IAAI,CAAC,CAAC;IAC/F,GAAG,CAAC,yEAAyE,SAAS,IAAI,CAAC,CAAC;IAE5F,MAAM,CAAC,GAAG,IAAI,CAAC;QACb,MAAM,EAAE,gBAAgB;QACxB,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;QAChC,gBAAgB,EAAE,IAAI;QACtB,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;KACzB,CAAC,CAAC;IAEH,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;AACpB,CAAC"}

package/dist/dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { DbHandles } from './db.js';
+import type { Embedder } from './embedder.js';
+export declare function callTool(h: DbHandles, embedder: Embedder, name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/dispatch.js

@@ -0,0 +1,43 @@
+import { store, query, recall, recallDocs, lexical, reindex, exportRange } from './memory.js';
+// Route a bare MCP tool name + arguments to the memory store and return the RAW
+// result. The index.ts CallTool handler wraps this in the MCP content envelope;
+// keeping the routing here (free of any MCP transport) makes the tool surface
+// unit-testable. Throws on an unknown tool.
+export async function callTool(h, embedder, name, args) {
+    const a = args;
+    switch (name) {
+        case 'store':
+            return store(h, embedder, {
+                content: String(a.content),
+                source: a.source,
+                observed: a.observed,
+                date: a.date,
+                tags: Array.isArray(a.tags) ? a.tags : undefined,
+                meta: a.meta,
+                supersedes: a.supersedes,
+            });
+        case 'query':
+            return query(h, {
+                source: a.source,
+                observed: a.observed,
+                tag: a.tag,
+                since: a.since,
+                until: a.until,
+                liveOnly: a.live_only,
+                limit: a.limit,
+            });
+        case 'recall':
+            return recall(h, embedder, String(a.text), a.k ?? 5);
+        case 'recall_docs':
+            return recallDocs(h, embedder, String(a.text), a.k ?? 5);
+        case 'lexical':
+            return lexical(h, String(a.text), a.k ?? 50);
+        case 'reindex':
+            return reindex(h, embedder, String(a.root));
+        case 'export_range':
+            return exportRange(h, String(a.since), String(a.until));
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE9F,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,4CAA4C;AAC5C,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,CAAY,EACZ,QAAkB,EAClB,IAAY,EACZ,IAA6B;IAE7B,MAAM,CAAC,GAAG,IAAI,CAAC;IACf,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE;gBACxB,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;gBAC1B,MAAM,EAAE,CAAC,CAAC,MAA4B;gBACtC,QAAQ,EAAE,CAAC,CAAC,QAA8B;gBAC1C,IAAI,EAAE,CAAC,CAAC,IAA0B;gBAClC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,IAAiB,CAAC,CAAC,CAAC,SAAS;gBAC9D,IAAI,EAAE,CAAC,CAAC,IAA2C;gBACnD,UAAU,EAAE,CAAC,CAAC,UAAgC;aAC/C,CAAC,CAAC;QACL,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,CAAC,EAAE;gBACd,MAAM,EAAE,CAAC,CAAC,MAA4B;gBACtC,QAAQ,EAAE,CAAC,CAAC,QAA8B;gBAC1C,GAAG,EAAE,CAAC,CAAC,GAAyB;gBAChC,KAAK,EAAE,CAAC,CAAC,KAA2B;gBACpC,KAAK,EAAE,CAAC,CAAC,KAA2B;gBACpC,QAAQ,EAAE,CAAC,CAAC,SAAgC;gBAC5C,KAAK,EAAE,CAAC,CAAC,KAA2B;aACrC,CAAC,CAAC;QACL,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAG,CAAC,CAAC,CAAY,IAAI,CAAC,CAAC,CAAC;QACnE,KAAK,aAAa;YAChB,OAAO,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAG,CAAC,CAAC,CAAY,IAAI,CAAC,CAAC,CAAC;QACvE,KAAK,SAAS;YACZ,OAAO,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAG,CAAC,CAAC,CAAY,IAAI,EAAE,CAAC,CAAC;QAC3D,KAAK,SAAS;YACZ,OAAO,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9C,KAAK,cAAc;YACjB,OAAO,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1D;YACE,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/embedder.d.ts

@@ -0,0 +1,18 @@
+export type Vec = Float32Array;
+export interface Embedder {
+    embed(text: string): Promise<Vec>;
+}
+export declare function vecToBuffer(v: Vec): Buffer;
+/** Deterministic, dependency-free embedder for hermetic unit tests. */
+export declare class FakeEmbedder implements Embedder {
+    private dim;
+    constructor(dim?: number);
+    embed(text: string): Promise<Vec>;
+}
+/** Calls a local Ollama /api/embeddings endpoint. */
+export declare class OllamaEmbedder implements Embedder {
+    private model;
+    private baseUrl;
+    constructor(model?: string, baseUrl?: string);
+    embed(text: string): Promise<Vec>;
+}

package/dist/embedder.js

@@ -0,0 +1,44 @@
+export function vecToBuffer(v) {
+    return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+}
+/** Deterministic, dependency-free embedder for hermetic unit tests. */
+export class FakeEmbedder {
+    dim;
+    constructor(dim = 1024) {
+        this.dim = dim;
+    }
+    async embed(text) {
+        const v = new Float32Array(this.dim);
+        let h = 2166136261 >>> 0;
+        for (let i = 0; i < text.length; i++) {
+            h ^= text.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+        }
+        for (let i = 0; i < this.dim; i++) {
+            h = Math.imul(h ^ (h >>> 13), 16777619);
+            v[i] = (h >>> 0) % 1000 / 1000;
+        }
+        return v;
+    }
+}
+/** Calls a local Ollama /api/embeddings endpoint. */
+export class OllamaEmbedder {
+    model;
+    baseUrl;
+    constructor(model = 'qwen3-embedding:0.6b', baseUrl = process.env.OLLAMA_BASE_URL ?? 'http://localhost:11434') {
+        this.model = model;
+        this.baseUrl = baseUrl;
+    }
+    async embed(text) {
+        const res = await fetch(`${this.baseUrl}/api/embeddings`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ model: this.model, prompt: text }),
+        });
+        if (!res.ok)
+            throw new Error(`Ollama embeddings failed: ${res.status} ${await res.text()}`);
+        const json = (await res.json());
+        return Float32Array.from(json.embedding);
+    }
+}
+//# sourceMappingURL=embedder.js.map

package/dist/embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.js","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,WAAW,CAAC,CAAM;IAChC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;AAC3D,CAAC;AAED,uEAAuE;AACvE,MAAM,OAAO,YAAY;IACH;IAApB,YAAoB,MAAM,IAAI;QAAV,QAAG,GAAH,GAAG,CAAO;IAAG,CAAC;IAClC,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,CAAC,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG,UAAU,KAAK,CAAC,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;QACjC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;CACF;AAED,qDAAqD;AACrD,MAAM,OAAO,cAAc;IAEf;IACA;IAFV,YACU,QAAQ,sBAAsB,EAC9B,UAAU,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,wBAAwB;QADjE,UAAK,GAAL,KAAK,CAAyB;QAC9B,YAAO,GAAP,OAAO,CAA0D;IACxE,CAAC;IACJ,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,iBAAiB,EAAE;YACxD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;SAC1D,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,CAAC,MAAM,IAAI,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5F,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA4B,CAAC;QAC3D,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/dist/enrichment.d.ts

@@ -0,0 +1,58 @@
+import type { DbHandles } from './db.js';
+import type { Embedder } from './embedder.js';
+interface SalienceExtractor {
+    extractSalient(turn: {
+        text: string;
+        source?: string;
+        observed?: string;
+        date?: string;
+        meta?: Record<string, unknown>;
+    }): Promise<EnrichmentCandidate[]>;
+}
+/** Below this vector distance two memories are treated as near-duplicates. */
+export declare const DEDUPE_DISTANCE = 0.15;
+/** Drop candidates whose salience is below this score. */
+export declare const SALIENCE_THRESHOLD = 0.5;
+/** A distilled candidate memory produced by an (external) salience extractor. */
+export interface EnrichmentCandidate {
+    content: string;
+    salience: number;
+    source?: string;
+    observed?: string;
+    date?: string;
+    tags?: string[];
+    meta?: Record<string, unknown>;
+    /**
+     * If set, this candidate supersedes the given memory id — an upstream
+     * contradiction/update judgment (e.g. from the salience salience step).
+     * enrich() honors it: the new row is written and the old row is flagged
+     * superseded (history kept, never overwritten), even past the dedupe check.
+     */
+    supersedes?: number | null;
+}
+export interface EnrichmentResult {
+    written: number[];
+    superseded: number[];
+    skipped: number;
+}
+/**
+ * Fold a batch of candidate memories into the store: dedupe, supersede stale
+ * beliefs (keeping history), and write the survivors with provenance.
+ *
+ * NOTE: candidates are produced UPSTREAM. This function owns dedupe + write
+ * only — it does not call any model.
+ */
+export declare function enrich(h: DbHandles, embedder: Embedder, candidates: EnrichmentCandidate[]): Promise<EnrichmentResult>;
+/**
+ * Post-turn entry point: extract salient candidates from a turn, then enrich.
+ *
+ * The extraction step is delegated to the sibling @justfortytwo/salience
+ * engine via an INJECTED SalienceExtractor — memory owns dedupe + write, never the
+ * model client. The host builds the extractor (salience's createSalienceExtractor
+ * with its own LlmClient) and passes it in here.
+ */
+export declare function enrichFromTurn(h: DbHandles, embedder: Embedder, turn: {
+    text: string;
+    source?: string;
+}, extractor: SalienceExtractor): Promise<EnrichmentResult>;
+export {};

package/dist/enrichment.js

@@ -0,0 +1,109 @@
+import { recall, store } from './memory.js';
+// ===========================================================================
+// Continuous enrichment — STUB.
+//
+// Goal: after each conversational turn, distil durable knowledge from the turn
+// and fold it into the memory store WITHOUT ever silently destroying a prior
+// belief. This is the write-side counterpart to recall: recall reads, enrichment
+// curates what is worth remembering.
+//
+// PIPELINE (post-turn):
+//
+//   1. SALIENCE EXTRACTION
+//      Take the turn (user + assistant text, tool results) and extract a small
+//      set of candidate memories — atomic, self-contained statements worth
+//      keeping ("the owner's child is named X", "the deploy script lives at Y").
+//      Each candidate carries a salience score; below a threshold we drop it so
+//      the store does not fill with noise.
+//      The extractor is model-driven, and the LLM call is NOT owned by this
+//      package (a memory server must not embed a model client). The salience
+//      step lives in the sibling `@justfortytwo/salience` engine, which
+//      defines a `SalienceExtractor` (injected `LlmClient`) and returns scored
+//      candidates. We inject that extractor and pass its candidates IN to
+//      enrich(); this file owns only dedupe + write.
+//
+//   2. DEDUPE / SUPERSEDE  (recency wins, history is kept, NEVER overwrite)
+//      For each candidate, semantically recall the nearest existing memories.
+//        - near-duplicate (distance below DEDUPE_DISTANCE) and same meaning:
+//            skip the write — we already know this.
+//        - contradiction / update of an existing belief:
+//            write the new memory and SUPERSEDE the old row (memory.store with
+//            `supersedes`). The old row is retained and flagged superseded_by,
+//            so the history of what we believed and when is fully auditable.
+//            Recency wins for live recall; nothing is deleted.
+//      TODO(impl): "same meaning" vs "contradiction" needs more than vector
+//        distance (two close vectors can be opposite facts). This likely needs
+//        the same sibling salience step as (1) to judge the relation.
+//
+//   3. WRITE  (tagged provenance)
+//      Persist surviving candidates via memory.store, tagged with:
+//        - source:   where the knowledge came from (e.g. the channel/actor)
+//        - observed: how we came to believe it (e.g. "stated" vs "inferred")
+//        - date:     when it was observed
+//      Inferred memories MUST be marked observed:"inferred" so downstream
+//      consumers can weight stated facts over guesses.
+//
+// The contract: enrichment is ADDITIVE and AUDITABLE. A wrong inference can be
+// superseded later; it is never silently erased.
+// ===========================================================================
+/** Below this vector distance two memories are treated as near-duplicates. */
+export const DEDUPE_DISTANCE = 0.15;
+/** Drop candidates whose salience is below this score. */
+export const SALIENCE_THRESHOLD = 0.5;
+/**
+ * Fold a batch of candidate memories into the store: dedupe, supersede stale
+ * beliefs (keeping history), and write the survivors with provenance.
+ *
+ * NOTE: candidates are produced UPSTREAM. This function owns dedupe + write
+ * only — it does not call any model.
+ */
+export async function enrich(h, embedder, candidates) {
+    const written = [];
+    const superseded = [];
+    let skipped = 0;
+    for (const c of candidates) {
+        if (c.salience < SALIENCE_THRESHOLD) {
+            skipped++;
+            continue;
+        }
+        // Dedupe by meaning — unless the candidate explicitly supersedes a prior row,
+        // in which case the update is intentional even if it reads similar. Note:
+        // recall is live-only, so we dedupe against LIVE memories, not superseded
+        // history (a candidate matching a dead row is intentionally re-written).
+        if (c.supersedes == null) {
+            const near = await recall(h, embedder, c.content, 1);
+            if (near.length > 0 && near[0].distance < DEDUPE_DISTANCE) {
+                skipped++;
+                continue;
+            }
+        }
+        const id = await store(h, embedder, {
+            content: c.content,
+            source: c.source,
+            observed: c.observed,
+            date: c.date,
+            tags: c.tags,
+            meta: c.meta,
+            supersedes: c.supersedes ?? null,
+        });
+        written.push(id);
+        if (c.supersedes != null)
+            superseded.push(c.supersedes);
+    }
+    return { written, superseded, skipped };
+}
+/**
+ * Post-turn entry point: extract salient candidates from a turn, then enrich.
+ *
+ * The extraction step is delegated to the sibling @justfortytwo/salience
+ * engine via an INJECTED SalienceExtractor — memory owns dedupe + write, never the
+ * model client. The host builds the extractor (salience's createSalienceExtractor
+ * with its own LlmClient) and passes it in here.
+ */
+export async function enrichFromTurn(h, embedder, turn, extractor) {
+    // memory owns dedupe + write; the salience extraction (the model call) is the
+    // injected @justfortytwo/salience engine's. We only wire the two together.
+    const candidates = await extractor.extractSalient(turn);
+    return enrich(h, embedder, candidates);
+}
+//# sourceMappingURL=enrichment.js.map

package/dist/enrichment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment.js","sourceRoot":"","sources":["../src/enrichment.ts"],"names":[],"mappings":"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"}

package/dist/gate-approval-store.d.ts

@@ -0,0 +1,17 @@
+import type { ApprovalStore, AuditLogger, AuditEntry, PendingApproval, AddPendingInput } from '@justfortytwo/gate';
+import type { DbHandles } from './db.js';
+/**
+ * SQLite-backed ApprovalStore + AuditLogger for the gate. Pass an instance
+ * to gate's `decide(manifest, ctx, { store, audit })` so staged one-shots and the
+ * audit trail live in memory's durable db instead of the gate's JSONL default.
+ */
+export declare class GateApprovalStore implements ApprovalStore, AuditLogger {
+    private readonly h;
+    constructor(h: DbHandles);
+    addPending(input: AddPendingInput): Promise<string>;
+    getByToolUseId(toolUseId: string): Promise<PendingApproval | undefined>;
+    markExecutedByToolUseId(toolUseId: string): Promise<boolean>;
+    setDecisionByToolUseId(toolUseId: string, status: 'approved' | 'denied', by?: string): Promise<boolean>;
+    list(): Promise<PendingApproval[]>;
+    log(entry: AuditEntry): Promise<void>;
+}