@saihm/shm 0.0.0-stage → 0.38.1

package/LICENSE

@@ -0,0 +1,97 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             SAIHM Project
+Licensed Work:        SHM (Super-Human Memory) 0.38.1
+                      The Licensed Work is (c) 2026 SAIHM Project.
+Additional Use Grant: You may make production use of the Licensed Work if
+                      you hold a paid SAIHM subscription (a PRO, PRO_FAST,
+                      ENTERPRISE or ENTERPRISE_FAST tier, or a successor
+                      paid tier) and use the Licensed Work with the SAIHM
+                      account that holds that subscription.
+Change Date:          2030-10-03
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please visit: https://github.com/sponsors/SAIHM-Admin
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/NOTICE

@@ -0,0 +1,12 @@
+SHM (Super-Human Memory)
+Copyright 2026 SAIHM Project
+
+Licensed under the Business Source License 1.1. See LICENSE.
+
+This package contains no third-party code. It depends on packages that npm
+installs separately, each under its own licence, among them
+@xenova/transformers (Apache License 2.0).
+
+At run time, the default embedder (Xenova/all-MiniLM-L6-v2) and the optional
+cross-encoder reranker (Xenova/ms-marco-MiniLM-L-6-v2) load pretrained models
+from the Hugging Face Hub. Each model is published under its own licence.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# SHM — Super-Human Memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The right memory, at the right moment.** SHM brings your AI agent the memories that
+matter for the task in front of it — ranked, on time, and encrypted on your machine. It
+is the layer on top of [SAIHM](https://github.com/SAIHM-Admin/saihm-mcp-server-pro)
+that puts that memory to work.
+
+[![npm version](https://img.shields.io/npm/v/@saihm/shm.svg)](https://www.npmjs.com/package/@saihm/shm)
+[![license](https://img.shields.io/npm/l/@saihm/shm.svg)](./LICENSE)
+[![Star on GitHub](https://img.shields.io/badge/GitHub-Star-181717?logo=github&logoColor=white)](https://github.com/SAIHM-Admin/saihm-shm)
+[![Sponsor SAIHM](https://img.shields.io/badge/Sponsor-SAIHM-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/SAIHM-Admin)
+[![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@SAIHM-Memory?sub_confirmation=1)
+[![Follow on X](https://img.shields.io/badge/X-Follow-000000?logo=x&logoColor=white)](https://x.com/SAIHMemory)
+
+<table>
+  <tr>
+    <td width="50%"><a href="https://www.youtube.com/watch?v=yCWfsGnp0rE"><img src="https://img.youtube.com/vi/yCWfsGnp0rE/maxresdefault.jpg" alt="Watch on YouTube: SAIHM Short Overview, 6 minutes" width="100%"></a></td>
+    <td width="50%"><a href="https://www.youtube.com/watch?v=t3rXudDKank"><img src="https://img.youtube.com/vi/t3rXudDKank/maxresdefault.jpg" alt="Watch on YouTube: SAIHM Detailed Overview, 30 minutes" width="100%"></a></td>
+  </tr>
+  <tr>
+    <td align="center"><b>▶ SAIHM Short Overview</b><br>6 minutes</td>
+    <td align="center"><b>▶ SAIHM Detailed Overview</b><br>30 minutes</td>
+  </tr>
+</table>
+
+**Enjoyed them?** Like the videos, [subscribe to the SAIHM channel](https://www.youtube.com/@SAIHM-Memory?sub_confirmation=1),
+and turn on notifications with the bell 🔔 to hear about new videos and updates.
+
+**Prefer to read?** [The SAIHM manual](https://saihm.net/manual) (PDF) is a
+decision-maker's guide to SAIHM and SHM.
+
+## What SHM gives you
+
+SAIHM keeps your agent's memory safe. SHM makes it work efficiently: it organises that
+memory and brings the right part of it forward, by meaning, before the agent asks.
+
+- **The right memories, not all of them.** SHM ranks what your agent remembers and
+  brings forward only what the current task needs, within a budget you set. The context
+  window stays clean and tasks stay apart.
+- **Ready before the question.** SHM puts the relevant memories in front of your agent
+  as the work begins, and records why each one was chosen.
+- **Private by design.** SHM runs on your side, next to your agent. Everything it stores
+  is encrypted under a key you hold, and its models run on your own machine.
+- **Erasure that reaches every copy SHM holds.** When a memory is erased in SAIHM, SHM removes it
+  from its index, its caches and everything it derived from it.
+- **Picks up where you left off.** SHM can save an encrypted snapshot of its state and
+  resume in a new session or on another device.
+
+## Who it's for
+
+SHM is for teams and builders whose agents hold a paid SAIHM subscription and want their
+memory to do more of the work. It runs beside any agent that reaches SAIHM, through the
+SAIHM client or an MCP client.
+
+## Get started
+
+```bash
+npm install @saihm/shm
+```
+
+You need Node.js 20.20 or later, a paid SAIHM subscription, and
+[`@saihm/mcp-server-pro`](https://github.com/SAIHM-Admin/saihm-mcp-server-pro) version
+0.13.0 or later. The [developer guide](#developer-guide) below takes you from install to
+your first ranked answer.
+
+## Support SHM
+
+If SHM is useful to you, here is how to help it reach more people:
+
+- **Star it on [GitHub](https://github.com/SAIHM-Admin/saihm-shm).** Stars help other developers find SHM.
+- **Share it** with a colleague, your team, or anyone whose assistant keeps forgetting.
+- **Follow [@SAIHMemory on X](https://x.com/SAIHMemory)** for news and updates.
+- **Sponsor it** through [GitHub Sponsors](https://github.com/sponsors/SAIHM-Admin), monthly or one-time.
+- **Follow along on YouTube:** like the videos, [subscribe to the channel](https://www.youtube.com/@SAIHM-Memory?sub_confirmation=1), and turn on notifications with the bell 🔔 for new videos and updates.
+
+---
+
+## Developer guide
+
+### Quickstart
+
+Point SHM at a folder of Markdown notes and ask it for the most relevant ones:
+
+```js
+import { randomBytes } from "node:crypto";
+import { openMemorySession } from "@saihm/shm/session";
+import { MarkdownDirPort } from "@saihm/shm/adapter";
+import { LocalMiniLmEmbedder } from "@saihm/shm/embed";
+import { EncryptedIndexStore } from "@saihm/shm/store";
+
+// Your SAIHM connection: any object whose status() returns your account status as SAIHM reports it —
+// your SAIHM client, or SHM's McpSaihmClient (below).
+const saihm = yourSaihmClient;
+
+const session = await openMemorySession({
+  entitlement: saihm,                              // checked first: a paid tier, or the session does not open
+  port: new MarkdownDirPort({ dir: "./notes" }),   // the memories to rank
+  embedder: new LocalMiniLmEmbedder(),             // runs locally
+  store: new EncryptedIndexStore({ dir: "./.shm", keyBytes: randomBytes(32) }),
+});
+
+const ids = await session.answerRetriever.select("What did we decide about the launch?", { maxK: 5 });
+console.log(ids);
+await session.close();
+```
+
+Keep the 32-byte key to reuse the encrypted index between runs; give SHM a new key and it builds a fresh index.
+
+### Reaching SAIHM through MCP
+
+If your agent talks to SAIHM through MCP, use SHM's `McpSaihmClient` as the status source. Give it a `callTool` function that runs one SAIHM tool through your MCP client and returns the result as the client gives it; SHM reads the result's `structuredContent`. With the official MCP SDK:
+
+```js
+import { McpSaihmClient } from "@saihm/shm/saihm";
+
+// `mcp` is your connected MCP SDK client.
+const callTool = (name, args) => mcp.callTool({ name, arguments: args });
+const saihm = new McpSaihmClient({ endpoint: "saihm", tenantId: "my-agent", callTool });
+// saihm.status() runs the saihm_status tool; pass `saihm` as `entitlement`.
+```
+
+### How access works
+
+Before a session opens, SHM confirms with SAIHM that your account holds a paid tier: `PRO`, `PRO_FAST`, `ENTERPRISE` or `ENTERPRISE_FAST`. The session opens as soon as the check passes; any other answer, an error or a timeout keeps it closed, and nothing is locked, written or read until then. The check waits up to 15 seconds by default (`entitlementTimeoutMs`). The first start of the SAIHM MCP server after an install or upgrade can take longer while it downloads, so start it once beforehand or raise the timeout.
+
+SHM takes the tier straight from your account status as SAIHM reports it, never from an environment variable or configuration file. The [licence](#licence) sets the terms of use.
+
+### What's inside
+
+- **Hybrid ranking.** Semantic and lexical retrieval fused with Reciprocal Rank Fusion, with an optional local cross-encoder reranker (`CrossEncoderReranker`). If the reranker's model cannot load, SHM keeps answering with the base ranking.
+- **Proactive context.** `session.proactiveInjector()` assembles the memories relevant to the current task within a budget you set, and records why each one was chosen.
+- **Encryption at rest.** The index and any persisted memory bodies are encrypted with AES-256-GCM under a key you hold.
+- **Your sources.** SHM ranks whatever its read port supplies: a folder of Markdown (`MarkdownDirPort`), your own adapter over another store, or several sources federated together (`FederatedReadPort`). Through `McpSaihmClient` it reads and writes SAIHM cells: recall by query, cells shared with you, and the knowledge SHM derives.
+- **Resident service.** A resident service (`ResidentSession`, `serveHttp`) keeps the index warm, and host hooks (`HostHookAdapter`) bring relevant memories into a coding session.
+
+The embedder and the reranker run on your machine. On first use they download their pretrained models from the Hugging Face Hub and cache them.
+
+### SHM and the SAIHM MCP server
+
+SHM builds on [`@saihm/mcp-server-pro`](https://github.com/SAIHM-Admin/saihm-mcp-server-pro), version 0.13.0 or later. The MCP server keeps SHM in step with your SAIHM memory:
+
+- **The change feed** tells SHM which of your memories were written, so SHM reads them again.
+- **The erasure feed** tells SHM which memories were erased, so SHM removes them and everything it derived from them.
+- **Share states** tell SHM which memories other agents have shared with you, and which of those shares have ended.
+- **Structured tool results** give SHM each answer in a form it checks before acting on it.
+- **Warm start** lets SHM save an encrypted snapshot of its state and pick up where it left off in a new session or on another device.
+
+### Your own endpoint
+
+You can run SHM against your own SAIHM endpoint. SAIHM is not responsible for, and has no comment regarding, endpoints developed and run by others.
+
+## Licence
+
+SHM is licensed under the [Business Source License 1.1](LICENSE). Production use is granted to holders of a paid SAIHM subscription who use SHM with the SAIHM account that holds it. For any other production use, a commercial licence is available through [GitHub Sponsors](https://github.com/sponsors/SAIHM-Admin). Each version converts to the Apache License, Version 2.0 on its Change Date, stated in LICENSE.
+
+See [NOTICE](NOTICE) for third-party notices and [CONTRIBUTING.md](CONTRIBUTING.md) for contributions and security reports.
+
+---
+
+SHM is developed by SAIHM Project.

package/dist/adapter/epoch.d.ts

@@ -0,0 +1,4 @@
+export declare function hourlyEpoch(ms: number): number;
+export declare const EPOCH_KEYS: readonly ["updated", "date"];
+export declare function epochFromFrontmatter(frontmatter: ReadonlyMap<string, string>): number | undefined;
+//# sourceMappingURL=epoch.d.ts.map

package/dist/adapter/epoch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch.d.ts","sourceRoot":"","sources":["../../src/adapter/epoch.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,eAAO,MAAM,UAAU,8BAA+B,CAAC;AAEvD,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAQjG"}

package/dist/adapter/epoch.js

@@ -0,0 +1,16 @@
+export function hourlyEpoch(ms) {
+    return Number.isFinite(ms) && ms > 0 ? Math.floor(ms / 3_600_000) : 0;
+}
+export const EPOCH_KEYS = ["updated", "date"];
+export function epochFromFrontmatter(frontmatter) {
+    for (const k of EPOCH_KEYS) {
+        const v = frontmatter.get(k)?.trim();
+        if (v === undefined || v === "")
+            continue;
+        const ms = Date.parse(v);
+        if (Number.isFinite(ms) && ms > 0)
+            return hourlyEpoch(ms);
+    }
+    return undefined;
+}
+//# sourceMappingURL=epoch.js.map

package/dist/adapter/epoch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch.js","sourceRoot":"","sources":["../../src/adapter/epoch.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,MAAM,CAAU,CAAC;AAEvD,MAAM,UAAU,oBAAoB,CAAC,WAAwC;IAC3E,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE;YAAE,SAAS;QAC1C,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;YAAE,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/adapter/frontmatter.d.ts

@@ -0,0 +1,19 @@
+import { type LifecycleStamp } from "../retrieval/thread_lifecycle.js";
+export interface ParsedDocument {
+    readonly frontmatter: ReadonlyMap<string, string>;
+    readonly metadata: ReadonlyMap<string, string>;
+    readonly keys: ReadonlyMap<string, string>;
+    readonly body: string;
+}
+export declare function parseFrontmatter(text: string): ParsedDocument;
+export declare function stampFromDocument(text: string): LifecycleStamp;
+export declare function deriveLabel(text: string, maxChars?: number): string;
+export interface DocumentDescription {
+    readonly label: string;
+    readonly stamp: LifecycleStamp;
+    readonly body: string;
+    readonly epoch?: number;
+}
+export declare function describeDocument(text: string, maxChars?: number): DocumentDescription;
+export declare function truncateCodePoints(s: string, maxChars: number): string;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/adapter/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/adapter/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAGvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAiC7D;AAOD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAE9D;AAsBD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,MAAM,CAEhE;AAQD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,mBAAmB,CAIlF;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtE"}

package/dist/adapter/frontmatter.js

@@ -0,0 +1,95 @@
+import { parseLifecycle } from "../retrieval/thread_lifecycle.js";
+import { epochFromFrontmatter } from "./epoch.js";
+const METADATA_BLOCK = "metadata";
+const STAMP_KEYS = ["thread", "status", "kind", "conventionVersion", "convention-version"];
+export function parseFrontmatter(text) {
+    const src = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const m = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/.exec(src);
+    if (!m)
+        return { frontmatter: new Map(), metadata: new Map(), keys: new Map(), body: src };
+    const fm = new Map();
+    const meta = new Map();
+    let inMeta = false;
+    let metaSeen = false;
+    let childIndent;
+    for (const line of (m[1] ?? "").split(/\r?\n/)) {
+        const kv = /^([A-Za-z_][A-Za-z0-9_-]*)[ \t]*:[ \t]*(.*)$/.exec(line);
+        if (kv) {
+            const key = kv[1];
+            const value = unquote((kv[2] ?? "").trim());
+            inMeta = key === METADATA_BLOCK && value === "" && !metaSeen;
+            if (key === METADATA_BLOCK)
+                metaSeen = true;
+            if (fm.has(key))
+                continue;
+            fm.set(key, value);
+            continue;
+        }
+        if (!inMeta)
+            continue;
+        const child = /^([ \t]+)([A-Za-z_][A-Za-z0-9_-]*)[ \t]*:[ \t]*(.*)$/.exec(line);
+        if (!child) {
+            if (/^\S/.test(line))
+                inMeta = false;
+            continue;
+        }
+        childIndent ??= child[1];
+        if (child[1] !== childIndent)
+            continue;
+        if (!meta.has(child[2]))
+            meta.set(child[2], unquote((child[3] ?? "").trim()));
+    }
+    const keys = new Map(meta);
+    for (const [k, v] of fm)
+        keys.set(k, v);
+    return { frontmatter: fm, metadata: meta, keys, body: src.slice(m[0].length) };
+}
+function unquote(v) {
+    const q = v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")));
+    return q ? v.slice(1, -1) : v;
+}
+export function stampFromDocument(text) {
+    return stampOfParsed(parseFrontmatter(text));
+}
+function stampOfParsed({ keys: frontmatter, body }) {
+    const pairs = [];
+    for (const k of STAMP_KEYS) {
+        const v = frontmatter.get(k);
+        if (v !== undefined && v !== "")
+            pairs.push(`${k}: ${v}`);
+    }
+    const fromFm = pairs.length > 0 ? parseLifecycle(pairs.join(" ")) : {};
+    const firstLine = body.slice(0, indexOfLineEnd(body));
+    const fromLine1 = parseLifecycle(firstLine);
+    return {
+        ...fromLine1,
+        ...fromFm,
+    };
+}
+function indexOfLineEnd(s) {
+    const i = s.indexOf("\n");
+    return i === -1 ? s.length : i;
+}
+export function deriveLabel(text, maxChars = 120) {
+    return labelOfParsed(parseFrontmatter(text), maxChars);
+}
+function labelOfParsed({ keys: frontmatter, body }, maxChars) {
+    const desc = (frontmatter.get("description") ?? "").trim();
+    const label = desc !== "" ? desc : body.replace(/\s+/g, " ").trim();
+    return truncateCodePoints(label, maxChars);
+}
+export function describeDocument(text, maxChars = 120) {
+    const parsed = parseFrontmatter(text);
+    const epoch = epochFromFrontmatter(parsed.keys);
+    return { label: labelOfParsed(parsed, maxChars), stamp: stampOfParsed(parsed), body: parsed.body, ...(epoch !== undefined ? { epoch } : {}) };
+}
+export function truncateCodePoints(s, maxChars) {
+    if (maxChars <= 0)
+        return "";
+    if (s.length <= maxChars)
+        return s;
+    const cut = s.slice(0, maxChars);
+    const last = cut.charCodeAt(cut.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/adapter/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/adapter/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,MAAM,kCAAkC,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AASlD,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,mBAAmB,EAAE,oBAAoB,CAAU,CAAC;AAEpG,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjE,MAAM,CAAC,GAAG,yDAAyD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9E,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,WAAW,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAC3F,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,WAA+B,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/C,MAAM,EAAE,GAAG,8CAA8C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrE,IAAI,EAAE,EAAE,CAAC;YACP,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC;YACnB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC5C,MAAM,GAAG,GAAG,KAAK,cAAc,IAAI,KAAK,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC;YAC7D,IAAI,GAAG,KAAK,cAAc;gBAAE,QAAQ,GAAG,IAAI,CAAC;YAC5C,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC1B,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACnB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,KAAK,GAAG,sDAAsD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,MAAM,GAAG,KAAK,CAAC;YACrC,SAAS;QACX,CAAC;QACD,WAAW,KAAK,KAAK,CAAC,CAAC,CAAE,CAAC;QAC1B,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,WAAW;YAAE,SAAS;QACvC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAiB,IAAI,CAAC,CAAC;IAC3C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxC,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,SAAS,OAAO,CAAC,CAAS;IACxB,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9G,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,aAAa,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,aAAa,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAkB;IAChE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO;QACL,GAAG,SAAS;QACZ,GAAG,MAAM;KACV,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,CAAS;IAC/B,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,QAAQ,GAAG,GAAG;IACtD,OAAO,aAAa,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,aAAa,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAkB,EAAE,QAAgB;IAClF,MAAM,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACpE,OAAO,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC7C,CAAC;AASD,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAQ,GAAG,GAAG;IAC3D,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAChJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAS,EAAE,QAAgB;IAC5D,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7B,IAAI,CAAC,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5C,OAAO,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACnE,CAAC"}

package/dist/adapter/index.d.ts

@@ -0,0 +1,4 @@
+export { parseFrontmatter, stampFromDocument, describeDocument, deriveLabel, truncateCodePoints, type ParsedDocument, type DocumentDescription, } from "./frontmatter.js";
+export { hourlyEpoch, epochFromFrontmatter, EPOCH_KEYS } from "./epoch.js";
+export { MarkdownDirPort, federatedStampOf, type MarkdownDirPortOptions, type MarkdownDirStats, type StampSource, type StampedSource, } from "./markdown_dir_port.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC"}

package/dist/adapter/index.js

@@ -0,0 +1,4 @@
+export { parseFrontmatter, stampFromDocument, describeDocument, deriveLabel, truncateCodePoints, } from "./frontmatter.js";
+export { hourlyEpoch, epochFromFrontmatter, EPOCH_KEYS } from "./epoch.js";
+export { MarkdownDirPort, federatedStampOf, } from "./markdown_dir_port.js";
+//# sourceMappingURL=index.js.map

package/dist/adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,GAGnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EACL,eAAe,EACf,gBAAgB,GAKjB,MAAM,wBAAwB,CAAC"}

package/dist/adapter/markdown_dir_port.d.ts

@@ -0,0 +1,48 @@
+import type { IndexEntry, RecalledBody, SaihmReadPort } from "../saihm_client/types.js";
+import type { LifecycleStamp, StampLookup, StampSource } from "../retrieval/thread_lifecycle.js";
+export interface MarkdownDirPortOptions {
+    readonly dir: string;
+    readonly tenantId?: string;
+    readonly extensions?: readonly string[];
+    readonly exclude?: readonly string[];
+    readonly labelChars?: number;
+    readonly maxFileBytes?: number;
+    readonly recallCap?: number;
+}
+export interface MarkdownDirStats {
+    readonly files: number;
+    readonly skippedTooLarge: number;
+    readonly skippedVanished: number;
+    readonly stamped: number;
+    readonly dated: number;
+}
+export type { StampSource } from "../retrieval/thread_lifecycle.js";
+export declare class MarkdownDirPort implements SaihmReadPort, StampSource {
+    readonly tenantId: string;
+    private readonly dir;
+    private readonly extensions;
+    private readonly exclude;
+    private readonly labelChars;
+    private readonly maxFileBytes;
+    private readonly recallCap;
+    private docs;
+    private stampMap;
+    private skippedTooLarge;
+    private skippedVanished;
+    private datedCount;
+    constructor(opts: MarkdownDirPortOptions);
+    readonly stampOf: StampLookup;
+    stamps(): ReadonlyMap<string, LifecycleStamp>;
+    get stats(): MarkdownDirStats;
+    readIndex(): Promise<IndexEntry[]>;
+    recallByQuery(query: string): Promise<RecalledBody[]>;
+}
+export { hourlyEpoch } from "./epoch.js";
+export interface StampedSource {
+    readonly tag: string;
+    readonly port: StampSource;
+}
+export declare function federatedStampOf(sources: readonly StampedSource[], opts?: {
+    readonly separator?: string;
+}): StampLookup;
+//# sourceMappingURL=markdown_dir_port.d.ts.map

package/dist/adapter/markdown_dir_port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown_dir_port.d.ts","sourceRoot":"","sources":["../../src/adapter/markdown_dir_port.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAgBjG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAYD,YAAY,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,qBAAa,eAAgB,YAAW,aAAa,EAAE,WAAW;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,IAAI,CAAsB;IAClC,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,UAAU,CAAK;gBAEX,IAAI,EAAE,sBAAsB;IAUxC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAuE;IAEpG,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC;IAI7C,IAAI,KAAK,IAAI,gBAAgB,CAY5B;IAEK,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAiFlC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAY5D;AAOD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,IAAI,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACzC,WAAW,CAiBb"}