nlm-memory 0.5.1 → 0.5.3

package/README.md

@@ -1,27 +1,39 @@
-# nlm-memory
+<p align="center">
+  <strong>nlm-memory</strong><br/>
+  Local-first non-linear memory OS for AI operators
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/nlm-memory"><img src="https://img.shields.io/npm/v/nlm-memory?color=CB3837&label=npm&logo=npm" alt="npm version" /></a>
+  <a href="https://github.com/pbmagnet4/nlm-memory-ts/blob/main/LICENSE"><img src="https://img.shields.io/github/license/pbmagnet4/nlm-memory-ts?color=blue" alt="License: Apache 2.0" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/nlm-memory?color=brightgreen" alt="Node 20+" /></a>
+  <img src="https://img.shields.io/badge/tests-612%20passing-success" alt="612 tests passing" />
+  <img src="https://img.shields.io/badge/runtimes-9-8A2BE2" alt="9 runtimes supported" />
+  <img src="https://img.shields.io/badge/telemetry-none-informational" alt="Zero telemetry" />
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> &middot;
+  <a href="#quick-start">Quick Start</a> &middot;
+  <a href="#runtimes">Runtimes</a> &middot;
+  <a href="#how-recall-works">How recall works</a> &middot;
+  <a href="#mcp-tools">MCP</a> &middot;
+  <a href="#rest-api">REST API</a> &middot;
+  <a href="#daily-digest">Digest</a> &middot;
+  <a href="#configuration">Config</a> &middot;
+  <a href="#security">Security</a> &middot;
+  <a href="#vs-alternatives">vs Alternatives</a>
+</p>
 
-> Local-first memory OS for AI operators — one corpus across every runtime you use.
+---
 
-`nlm-memory` indexes every session from Claude Code, Codex, OpenCode, Cursor, Windsurf, Hermes, Aider, and pi into a single searchable store on your machine. Three properties no competitor ships together:
+`nlm-memory` indexes every session from Claude Code, Codex, OpenCode, Cursor, Windsurf, Hermes, Aider, and pi into a single searchable store on your machine. Three properties no other memory layer ships together:
 
-1. **Cross-runtime reach.** One index spans every adapter — not one per runtime.
-2. **Editable timeline.** Sessions can be superseded, retired, or marked aborted. Memory is non-linear: patch history retroactively. No other memory layer lets you do this.
+1. **Cross-runtime reach.** One index, every adapter.
+2. **Editable timeline.** Sessions can be superseded, retired, or marked aborted. Patch history retroactively — no other tool lets you do this.
 3. **97.2% R@5 baseline.** On a 14-month corpus, keyword recall surfaces the right session in the top 5 on 97.2% of evaluator queries. No fine-tuning, no cloud, no account.
 
-Everything stays on your machine. No telemetry, no account required beyond your classifier of choice.
-
----
-
-## Requirements
-
-- **Node 20+**
-- **[Ollama](https://ollama.com)** running locally with `nomic-embed-text` pulled for semantic search:
-  ```sh
-  ollama pull nomic-embed-text
-  ```
-- **A classifier** — pick during setup:
-  - **DeepSeek cloud** (recommended for speed) — fast, cheap (~$0.002/session). Sends up to 30K chars of each session transcript to `api.deepseek.com`.
-  - **Ollama local** — fully offline. Slower; uses whichever chat model you select from your local pull list.
+Everything stays on your machine. No telemetry, no account beyond your classifier of choice.
 
 ---
 
@@ -32,49 +44,129 @@ npm install -g nlm-memory
 nlm setup
 ```
 
-`nlm setup` is the interactive first-run wizard. It asks you to pick your classifier, model, and which runtimes to connect (Claude Code, Codex, Hermes), then installs the daemon. After it finishes, open **http://localhost:3940/ui** — done.
-
-### Platform support
+`nlm setup` is the interactive first-run wizard. It picks your classifier + model, wires the runtimes you actually use, generates an `NLM_MCP_TOKEN`, hardens permissions on `~/.nlm/`, and installs the daemon supervisor for your platform.
 
 | Platform | Daemon | Notes |
 |---|---|---|
 | **macOS** | LaunchAgent at `~/Library/LaunchAgents/com.github.pbmagnet4.nlm-memory.plist` | Auto-starts on login |
-| **Linux** | systemd user unit at `~/.config/systemd/user/nlm.service` | Run `loginctl enable-linger $USER` on headless servers so the daemon survives logout |
-| **Windows** | Manual `nlm start` for now | Hook + MCP install paths are platform-aware; daemon supervisor lands in the next release |
+| **Linux** | systemd user unit at `~/.config/systemd/user/nlm.service` | Headless servers: `loginctl enable-linger $USER` so the daemon survives logout |
+| **Windows** | Manual `nlm start` for now | Hook + MCP install paths are platform-aware; supervisor lands next release |
+
+Stop or remove: `nlm uninstall`.
+
+---
+
+## Quick Start
+
+After `nlm setup` finishes, open **http://localhost:3940/ui** — the daemon is running. A 30-second sanity check:
 
-To stop or remove:
 ```sh
-nlm uninstall   # remove the daemon supervisor on your platform
+nlm recall "what was that pgvector decision"   # one-shot search from the shell
+nlm digest                                      # yesterday's activity at a glance
+nlm --version
 ```
 
 ---
 
+## Runtimes
+
+One corpus across every adapter. `nlm connect` wires hooks + MCP for each runtime:
+
+| Runtime | Connect | Sessions read from | Hooks |
+|---|---|---|---|
+| **Claude Code** | `nlm connect claude-code` | `~/.claude/projects/**/*.jsonl` | 5 (UserPromptSubmit, SessionStart, Stop, PreCompact, SubagentStart) |
+| **Codex CLI** | `nlm connect codex` | `~/.codex/sessions/` | Marketplace plugin |
+| **Hermes** | `nlm connect hermes` | Hermes session DB | MCP only |
+| **Hermes Agent** | `nlm connect hermes-agent` | Hermes plugin path | pre-turn, post-turn, lifecycle |
+| **Cursor** | `nlm connect cursor` | Cursor IDE chat DB | MCP only |
+| **Windsurf** | `nlm connect windsurf` | Windsurf user dir | MCP only |
+| **OpenCode** | adapter active | `~/.local/share/opencode/` | MCP only |
+| **Aider** | adapter active | `AIDER_CHAT_HISTORY_FILE` | MCP only |
+| **pi.dev** | adapter active | `~/.pi/sessions/` | MCP only |
+
+`nlm disconnect <runtime>` reverses any of the above.
+
+---
+
 ## How recall works
 
-Once installed, NLM runs as a quiet background daemon. Two ways your AI agents get to it:
+Two delivery paths. They share the same index.
 
 ### 1. Hooks (Claude Code) — automatic context injection
 
-`nlm connect claude-code` installs five hooks into `~/.claude/settings.json`:
+Five hooks installed into `~/.claude/settings.json`:
 
-- **UserPromptSubmit / SessionStart** — before each turn, NLM scores the prompt against your past sessions and silently prepends a pointer block listing the 0–3 most likely-relevant prior sessions. The model sees them as conversational context.
-- **Stop** — after the model responds, NLM scans the response for citations of surfaced session IDs to measure useful-hit rate.
-- **PreCompact / SubagentStart** — link conversations across compactions and subagent dispatches so threads stay coherent.
+| Event | What NLM does | Mode |
+|---|---|---|
+| **UserPromptSubmit** | Score the prompt, silently prepend pointer block listing 0–3 most likely-relevant prior sessions | live by default |
+| **SessionStart** | Cold-start agents (cron, background) hit this; same pointer-block delivery without a user prompt | live by default |
+| **Stop** | Scan the model's response for citations of surfaced session IDs → updates `useful_hit_rate` and builds the reranker training substrate | always on |
+| **PreCompact** | Flush the per-conversation surfaced-IDs memo so post-compaction recalls aren't gated | always on |
+| **SubagentStart** | Record parent→subagent links so threads stay coherent across dispatches | always on |
 
-Default mode is **live** (recall injected into prompts). Switch to **shadow** (log-only, no injection) by setting `NLM_HOOK_MODE=shadow` in your hook commands.
+Switch to **shadow** mode (log-only, no injection) anytime with `NLM_HOOK_MODE=shadow` on the hook command. Toggle for an existing install: re-run `nlm hook install` after changing the env var. The hook fails open — any error yields a clean exit and never blocks the model.
 
 ### 2. MCP — explicit tools any agent can call
 
+Container-hosted agents (Hermes WebUI, Codex CLI, etc.) hit the Streamable-HTTP `POST /mcp` endpoint with `Authorization: Bearer ${NLM_MCP_TOKEN}`. Stdio MCP is also supported for Claude Code via `~/.mcp.json`.
+
+---
+
+## MCP Tools
+
+| Tool | What it does |
+|---|---|
+| `recall_sessions` | Hybrid keyword+semantic search across the full session corpus. Returns label, started_at, snippet, match score. |
+| `get_session` | Full body of one session by ID. Includes enriched `supersedes` / `supersededBy` links (id + label + summary) so chasing corrected facts doesn't need a second round-trip. |
+| `recall_facts` | Search structured facts: decisions, open questions, project state. Filterable by entity and kind. |
+| `get_fact_history` | Full version history of one fact — how a decision evolved over time. |
+| `cite_session` | Mark a session as explicitly referenced. Drives the `useful_hit_rate` metric and the future learned reranker. |
+
+---
+
+## REST API
+
+Daemon binds `127.0.0.1:3940` (override with `NLM_PORT`). Selected endpoints:
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| GET | `/api/health` | Host-only | Liveness probe; returns `{version, status, service}` |
+| GET | `/api/recall` | Bearer/Origin | Hybrid recall — `?q=`, `?mode=keyword\|semantic\|hybrid`, `?limit=` |
+| GET | `/api/recall/stats` | Bearer/Origin | 7-day stats: total, hit_rate, useful_hit_rate, top queries |
+| GET | `/api/recall/recent` | Bearer/Origin | Last N recall events for live tail/telemetry |
+| GET | `/api/recall/cite-stats` | Bearer/Origin | Citation rate over `?days=` |
+| GET | `/api/session/:id` | Bearer/Origin | Full session body + supersedence links |
+| GET | `/api/recall/facts` | Bearer/Origin | Structured fact search |
+| GET | `/api/facts/history` | Bearer/Origin | Version chain for one fact |
+| GET | `/api/dataset` | Bearer/Origin | Full session list for the UI dataset view |
+| GET | `/api/live/recent-writes` | Bearer/Origin | Live tail of ingested sessions |
+| GET | `/api/data/backup` | Bearer/Origin | Streaming SQLite snapshot download |
+| POST | `/api/data/restore` | Bearer/Origin | Stage a snapshot for apply-on-restart |
+| POST | `/api/hook/pre-compact` | Bearer/Origin | Hook endpoint; flushes the surfaced-IDs memo |
+| ALL | `/mcp` | Bearer required | Streamable-HTTP MCP transport for container agents |
+
+`/api/*` is gated by three layers: 127.0.0.1 Host check (defeats DNS rebinding), Origin check when the browser sends one (defeats cross-origin drive-by), Bearer fallback when Origin is absent (server-to-server clients).
+
+---
+
+## Daily digest
+
+Once-a-day summary of yesterday's activity:
+
 ```sh
-nlm connect claude-code      # writes ~/.mcp.json + installs hooks
-nlm connect codex            # installs as a Codex marketplace plugin
-nlm connect hermes           # writes ~/.hermes/config.yaml (MCP)
-nlm connect hermes-agent     # installs as a NousResearch Hermes plugin (hooks + MCP)
+nlm digest                  # print to stdout
+nlm digest --telegram       # post to Telegram (TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID)
 ```
 
-Once wired, agents can call `recall_sessions` (search past conversations), `recall_facts` (decisions/open questions/project state), `get_session` (pull a full session), `get_fact_history` (how a decision evolved), and `cite_session` (explicitly mark a session as referenced).
+Reports 24h real-traffic (probes filtered), 7d hit_rate + useful_hit_rate, top 5 queries, and a **`WARN hook silent`** alert when Claude Code ran yesterday but no live hook fires were logged. That alert is the canary for post-install drift — node upgrades, `settings.json` hand-edits, and `dist/` moves silently break the hook while Claude Code keeps working. Setup-time smoke tests can't catch this; only the daily correlation can.
+
+Wire to cron for a morning push:
+
+```cron
+0 7 * * *  nlm digest --telegram >> ~/.nlm/logs/digest.log 2>&1
+```
 
-For container-hosted agents that can't use stdio MCP, the daemon also exposes Streamable-HTTP MCP at `POST /mcp`. Use the auto-generated `NLM_MCP_TOKEN` from `~/.nlm/.env` as a bearer.
+When the daemon is unreachable, `--telegram` still fires — posts a "daemon unreachable" alert instead of failing silently.
 
 ---
 
@@ -84,30 +176,88 @@ Open `http://localhost:3940/ui` after the daemon starts.
 
 | Page | What it shows |
 |---|---|
-| **Live** | Sessions being written in real time, recent reads and decisions |
+| **Live** | Sessions being written in real time, recent reads, recent decisions |
 | **Pulse** | System health — coherence, runtimes, stale entities, recent sessions |
-| **River** | Full session timeline with density controls and supersedence visualization |
-| **Thread** | Per-entity conversation history with runtime filters |
-| **Search** | Keyword, semantic, or hybrid recall with match snippets |
-| **Recall** | Adoption telemetry — is the memory system actually being used? |
+| **River** | Full session timeline with density controls + superseded-lane visualization |
+| **Thread** | Per-entity conversation history with runtime filters and ←/→ navigation |
+| **Search** | Keyword, semantic, or hybrid recall with match snippets and field-origin tags |
+| **Recall** | Adoption telemetry — useful_hit_rate, source breakdown, query log |
 | **Settings** | Sources, providers, classifier, data backup/restore |
 
 ---
 
+## Pipeline
+
+What happens when an AI runtime writes a session and you later recall it:
+
+```
+ingest:  runtime transcript (jsonl/sqlite)
+   -> adapter parses runtime-specific format
+   -> classifier (DeepSeek cloud or Ollama local) extracts label + entities + decisions + open questions
+   -> embedder (nomic-embed-text via Ollama) computes 768-dim vector
+   -> SQLite canonical store + FTS5 keyword index + sqlite-vec ANN index
+
+recall: prompt / query
+   -> tokenize + match scoring (label x3, entity-exact x4, decision x2, summary x1, phrase-bonus +5)
+   -> hybrid: BM25-style keyword + vector cosine, fused by score
+   -> select-top-N gate (per-fire cap 3, per-conversation cap 10)
+   -> pointer block prepended to model context (hooks) or returned as tool result (MCP)
+```
+
+---
+
+## Configuration
+
+### Environment variables
+
+| Var | Default | What |
+|---|---|---|
+| `NLM_PORT` | `3940` | Daemon bind port (loopback only) |
+| `NLM_DB_PATH` | `~/.nlm/canonical.sqlite` | SQLite canonical store location |
+| `NLM_HOOK_MODE` | `live` | `live` injects pointer block; `shadow` logs without injecting |
+| `NLM_HOOK_LOG` | `~/.nlm/hook-log.jsonl` | Hook fire log; powers digest's liveness alert |
+| `NLM_USEFUL_HIT_LOG` | `~/.nlm/useful-hit-log.jsonl` | Citation/useful-hit ledger |
+| `NLM_QUERY_LOG` | `~/.nlm/query-log.jsonl` | Recall query telemetry |
+| `NLM_CITATION_LOG` | `~/.nlm/citation-log.jsonl` | Stop-hook citation events |
+| `NLM_MCP_TOKEN` | auto-generated | 256-bit bearer for `/api/*` (non-browser) and `/mcp` |
+| `NLM_MCP_CONFIG` | `~/.mcp.json` | Path the `connect`/`disconnect` commands modify |
+| `NLM_CLASSIFIER` | `deepseek` | `deepseek` (cloud) or `ollama` (local) |
+| `NLM_CLASSIFIER_MODEL` | `deepseek-v4-flash` | Model id for the chosen provider |
+| `NLM_OLLAMA_URL` | `http://localhost:11434` | Override Ollama endpoint |
+| `NLM_ADAPTERS` | all | Comma-separated allowlist of adapters to enable |
+| `DEEPSEEK_API_KEY` | — | Required when classifier=deepseek |
+| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | — | Required for `nlm digest --telegram` |
+
+Adapter source paths can be overridden individually: `NLM_CLAUDE_PROJECTS_PATH`, `NLM_CODEX_CONFIG`, `NLM_CURSOR_DB_PATH`, `NLM_HERMES_SESSIONS_PATH`, `NLM_HERMES_AGENT_DB_PATH`, `NLM_WINDSURF_USER_DIR`, `OPENCODE_DB_PATH`, `PI_SESSIONS_PATH`, `AIDER_CHAT_HISTORY_FILE`.
+
+### Config file
+
+`~/.nlm/.env` — autoloaded by every CLI command. Mode `0600`, owned by you, never readable by other users. The setup wizard writes the initial keys; you can edit it directly.
+
+### Ports
+
+| Port | Process | Bind | Override |
+|---|---|---|---|
+| `3940` | Daemon HTTP API + MCP | `127.0.0.1` only | `NLM_PORT` |
+| `11434` | Ollama (embedding + local classifier) | localhost | `NLM_OLLAMA_URL` |
+
+---
+
 ## Security
 
 NLM is local-first by design. The daemon:
 
-- Binds to `127.0.0.1` only — never `0.0.0.0`.
-- Enforces Host + Origin checks on `/api/*` to block DNS rebinding and cross-origin drive-by.
-- Generates a 256-bit `NLM_MCP_TOKEN` on first run and persists to `~/.nlm/.env` (mode `0600`). All non-browser API requests (hooks, MCP container clients) authenticate with `Authorization: Bearer ${NLM_MCP_TOKEN}`.
-- Recursively enforces `0700` on `~/.nlm/` and `0600` on its contents on every start.
+- Binds to `127.0.0.1` only — never `0.0.0.0`
+- Enforces Host + Origin checks on `/api/*` to defeat DNS rebinding and cross-origin drive-by
+- Generates a 256-bit `NLM_MCP_TOKEN` on first run, persists to `~/.nlm/.env` (mode `0600`); non-browser clients authenticate with `Authorization: Bearer ${NLM_MCP_TOKEN}` compared with `timingSafeEqual`
+- Recursively enforces `0700` on `~/.nlm/` and `0600` on its contents on every start
 - Sends nothing outbound except:
-  - Ollama (`localhost:11434`) for embeddings + local classifier
-  - DeepSeek API (`api.deepseek.com`) — only when classifier is set to DeepSeek
+  - Ollama (`localhost:11434`) for embeddings and the local classifier path
+  - DeepSeek API (`api.deepseek.com`) when classifier is set to DeepSeek
+  - Telegram API (`api.telegram.org`) when `nlm digest --telegram` is invoked
   - Your AI runtime transcript files (read-only)
 
-No telemetry. No vendor calls. No account.
+No telemetry. No vendor pings. No account.
 
 Report vulnerabilities via [SECURITY.md](SECURITY.md).
 
@@ -123,13 +273,21 @@ Old installs have `NLM_HOOK_MODE=shadow` hardcoded in `~/.claude/settings.json`
 
 ---
 
-## How it differs from mem0 and graphiti
+## vs Alternatives
+
+| | **nlm-memory** | mem0 | Letta / MemGPT | Built-in (`CLAUDE.md`) |
+|---|---|---|---|---|
+| **Unit of memory** | Whole session + extracted markers | Atomic facts | Graph nodes + edges | Static file |
+| **Cross-runtime** | 9 adapters, one corpus | Per-app SDK integration | Per-app SDK integration | Per-runtime config |
+| **Editable timeline** | Sessions can be superseded, retired, aborted | Append-only fact log | Graph edits | Manual file edits |
+| **R@5 baseline** | 97.2% on 14mo corpus | published varies | published varies | n/a |
+| **External deps** | SQLite + Ollama (local) | Postgres or Qdrant | Postgres | none |
+| **Hosted offering** | none — local only | yes | yes | n/a |
+| **Account required** | none | yes (cloud tier) | yes | none |
+| **Telemetry** | none | yes | yes | none |
+| **License** | Apache 2.0 | Apache 2.0 | Apache 2.0 | — |
 
-- **Unit of memory:** whole sessions with extracted markers (decisions, open questions, entities), not individual facts or graph edges.
-- **Audience:** you querying your own past work, not an embedded SDK for app developers.
-- **Cross-runtime:** one corpus across Claude Code, Codex, OpenCode, Cursor, Windsurf, Hermes, and more. Competitors target one runtime.
-- **Editable timeline:** sessions can be superseded, retired, aborted. No other tool lets you retrofit memory — a record from 6 months ago can be corrected today.
-- **Local-only:** no hosted offering, no telemetry, no vendor dependency.
+The defining property is the editable timeline. mem0 and Letta append; NLM lets you reach back and mark a session as superseded by a newer one, retire one as no-longer-relevant, or flag one as aborted-mid-flight. The next recall surfaces the corrected version, not the stale one. A claim from 6 months ago can be patched today.
 
 ---
 
@@ -138,17 +296,17 @@ Old installs have `NLM_HOOK_MODE=shadow` hardcoded in `~/.claude/settings.json`
 ```sh
 git clone https://github.com/pbmagnet4/nlm-memory-ts
 cd nlm-memory-ts
-npm install        # install dependencies
-npm run build      # compile dist/ — commit the result, it ships in the repo
-npm run dev        # hot-reload daemon
-npm run ui:dev     # hot-reload UI at localhost:5173 (proxies /api to :3940)
-npm test           # 601 tests across 62 files
+npm install
+npm run build          # compile dist/ — commit the result, it ships in the repo
+npm run dev            # hot-reload daemon
+npm run ui:dev         # hot-reload UI at localhost:5173 (proxies /api to :3940)
+npm test               # 612 tests across 64 files
 npm run typecheck
 ```
 
-`dist/` is committed to the repo so the global install works without a build step on the user's machine. Rebuild and commit `dist/` whenever you change `src/`.
+Architecture: hexagonal. `src/core/` knows about ports (interfaces), not adapters. `src/cli/nlm.ts` is the composition root — the only file that wires concrete implementations (`SqliteSessionStore`, `OllamaClient`, `Hono`, `StdioServerTransport`). Adapters in `src/core/adapters/` are one-way: they parse runtime-specific session formats into NLM's canonical shape; nothing in the runtime sees NLM.
 
-Database lives at `~/.nlm/canonical.sqlite`. Override with `NLM_DB_PATH`.
+`dist/` is committed so `npm install -g` works without a build step. Rebuild + commit when you change `src/`.
 
 ---
 

package/dist/cli/digest.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `nlm digest` — compose a daily-activity digest from the running daemon and
+ * either print it to stdout (default) or POST it to Telegram.
+ *
+ * Talks to the daemon over HTTP so it works regardless of where the daemon is
+ * actually running. If the daemon is unreachable, the Telegram path posts a
+ * "daemon unreachable" alert instead of failing silently — the cron user is
+ * specifically watching for this telemetry, so silence is worse than noise.
+ */
+export interface DigestOptions {
+    readonly port: number;
+    readonly telegram: boolean;
+    readonly timeoutMs?: number;
+}
+export interface DigestResult {
+    readonly text: string;
+    readonly delivered: "stdout" | "telegram" | "telegram-alert";
+    readonly daemonReachable: boolean;
+}
+export declare function runDigest(opts: DigestOptions): Promise<DigestResult>;

package/dist/cli/digest.js

@@ -0,0 +1,142 @@
+/**
+ * `nlm digest` — compose a daily-activity digest from the running daemon and
+ * either print it to stdout (default) or POST it to Telegram.
+ *
+ * Talks to the daemon over HTTP so it works regardless of where the daemon is
+ * actually running. If the daemon is unreachable, the Telegram path posts a
+ * "daemon unreachable" alert instead of failing silently — the cron user is
+ * specifically watching for this telemetry, so silence is worse than noise.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { composeDigest, } from "../core/digest/compose.js";
+import { checkHookLiveness } from "../core/digest/hook-liveness.js";
+import { hookAuthHeaders } from "../hook/hook-auth.js";
+export async function runDigest(opts) {
+    const base = `http://localhost:${opts.port}`;
+    const timeoutMs = opts.timeoutMs ?? 8000;
+    let stats = null;
+    let recent = [];
+    let sessions = [];
+    let daemonError = null;
+    try {
+        const [statsRes, recentRes, datasetRes] = await Promise.all([
+            fetchJson(`${base}/api/recall/stats`, timeoutMs),
+            fetchJson(`${base}/api/recall/recent?limit=200`, timeoutMs),
+            fetchJson(`${base}/api/dataset`, timeoutMs * 2),
+        ]);
+        stats = statsRes;
+        recent = (recentRes.entries) ?? [];
+        sessions = (datasetRes.sessions) ?? [];
+    }
+    catch (e) {
+        daemonError = e instanceof Error ? e.message : String(e);
+    }
+    if (daemonError !== null || stats === null) {
+        const text = `NLM digest — ${todayStr()}\n\n` +
+            `Daemon unreachable at ${base}\n${daemonError ?? "no stats returned"}`;
+        if (opts.telegram) {
+            await postTelegram(text);
+            return { text, delivered: "telegram-alert", daemonReachable: false };
+        }
+        process.stdout.write(`${text}\n`);
+        return { text, delivered: "stdout", daemonReachable: false };
+    }
+    const hookLogPath = process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
+    const hookLogExists = existsSync(hookLogPath);
+    const hookLog = hookLogExists ? readHookLog(hookLogPath) : [];
+    const hookAlert = checkHookLiveness({
+        sessions,
+        hookLog,
+        hookLogPath,
+        hookLogExists,
+    });
+    const text = composeDigest({
+        stats,
+        recent,
+        port: opts.port,
+        hookAlert,
+    });
+    if (opts.telegram) {
+        await postTelegram(text);
+        return { text, delivered: "telegram", daemonReachable: true };
+    }
+    process.stdout.write(`${text}\n`);
+    return { text, delivered: "stdout", daemonReachable: true };
+}
+async function fetchJson(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            headers: hookAuthHeaders({ "user-agent": "nlm-digest/1.0" }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`${url} → ${res.status} ${res.statusText}`);
+        }
+        return await res.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function readHookLog(path) {
+    const out = [];
+    const raw = readFileSync(path, "utf8");
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // Corrupt line — skip silently. The digest is best-effort observability,
+            // not a parser test.
+        }
+    }
+    return out;
+}
+async function postTelegram(text) {
+    const token = process.env["TELEGRAM_BOT_TOKEN"];
+    const chatId = process.env["TELEGRAM_CHAT_ID"];
+    if (!token || !chatId) {
+        throw new Error("TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must be set for --telegram");
+    }
+    const url = `https://api.telegram.org/bot${token}/sendMessage`;
+    const body = new URLSearchParams({
+        chat_id: chatId,
+        text,
+        disable_web_page_preview: "true",
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/x-www-form-urlencoded",
+                "user-agent": "nlm-digest/1.0",
+            },
+            body,
+            signal: controller.signal,
+        });
+        const payload = (await res.json());
+        if (!payload.ok) {
+            throw new Error(`telegram api error: ${payload.description ?? "unknown"}`);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function todayStr() {
+    const d = new Date();
+    const weekday = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][d.getDay()];
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${weekday} ${y}-${m}-${day}`;
+}
+//# sourceMappingURL=digest.js.map

package/dist/cli/digest.js.map

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

package/dist/cli/nlm.d.ts

@@ -21,5 +21,6 @@
  *   nlm connect codex        — install Codex marketplace plugin
  *   nlm disconnect claude-code — remove MCP block from ~/.mcp.json
  *   nlm disconnect codex       — remove Codex plugin
+ *   nlm digest   — print a daily-activity digest (or --telegram to post)
  */
 export {};

package/dist/cli/nlm.js

@@ -21,6 +21,7 @@
  *   nlm connect codex        — install Codex marketplace plugin
  *   nlm disconnect claude-code — remove MCP block from ~/.mcp.json
  *   nlm disconnect codex       — remove Codex plugin
+ *   nlm digest   — print a daily-activity digest (or --telegram to post)
  */
 import { fileURLToPath } from "node:url";
 import { dirname, resolve, join } from "node:path";
@@ -63,6 +64,7 @@ import { MemoSweepScheduler } from "../core/hook/memo-sweep.js";
 import { isAgentLoaded, isBenignBootoutError } from "./launchctl-helpers.js";
 import { adapterFromSource } from "../core/adapters/from-source.js";
 import { scanUsefulHits } from "../core/recall/useful-scan.js";
+import { runDigest } from "./digest.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const MIGRATIONS_DIR = resolve(__dirname, "../../migrations");
@@ -1015,6 +1017,27 @@ program
     console.error(`nlm useful-scan: scanned ${result.total} recalls in the last ${opts.days}d — ${rate}` +
         (opts.dryRun ? " (dry-run)" : `, ${result.appended} appended`));
 });
+program
+    .command("digest")
+    .description("Compose a daily-activity digest from the running daemon (optionally post to Telegram)")
+    .option("-p, --port <n>", "daemon port", (v) => Number.parseInt(v, 10), Number.parseInt(process.env["NLM_PORT"] ?? "3940", 10))
+    .option("--telegram", "post to Telegram instead of printing to stdout (requires TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID)")
+    .action(async (opts) => {
+    autoloadEnv();
+    try {
+        const result = await runDigest({
+            port: opts.port,
+            telegram: opts.telegram === true,
+        });
+        if (!result.daemonReachable) {
+            process.exit(1);
+        }
+    }
+    catch (e) {
+        console.error("nlm digest:", e instanceof Error ? e.message : e);
+        process.exit(1);
+    }
+});
 program.parseAsync().catch((e) => {
     console.error("nlm: fatal", e);
     process.exit(1);