@chendpoc/pi-memory 0.1.12 → 0.2.0

package/README.md

@@ -1,224 +1,104 @@
-# @chendpoc/pi-memory
+# pi-memory
 
-[![npm](https://img.shields.io/npm/v/@chendpoc/pi-memory)](https://www.npmjs.com/package/@chendpoc/pi-memory)
+Cross-session episodic memory for the [Pi coding agent](https://pi.dev): **MEMORY.md** as ground truth, a JSONL Sidecar for vector retrieval, and Preflight injection before each user turn.
 
-Local episodic memory for [Pi](https://pi.dev) coding agent. Automatically recalls past sessions, people, projects, and decisions during conversations.
-
-**No external binaries required** --- pure TypeScript, runs entirely inside Pi.
-
-## Features
-
-- **Implicit memory preflight** --- automatically detects memory-relevant questions (Chinese/English/Japanese) and injects `<private_memory>` context before each LLM call
-- **`memory_recall` tool** --- LLM can explicitly query the knowledge graph by entity/relationship
-- **`memory_append` tool** --- persist user preferences and facts to `MEMORY.md`
-- **Local trainer** --- extracts entities, relations, and events from Pi session history (regex or LLM-powered)
-- **FTS5 search** --- SQLite full-text index for keyword fallback
-- **LLM rerank** --- reranks keyword search results using `deepseek-v4-flash` for relevance scoring
-- **Session dedup** --- content-hash deduplication in both trainer and indexer
-- **Zero config** --- works out of the box with `pi install`
-
-## Install
-
-```bash
-pi install npm:@chendpoc/pi-memory
-```
+## Architecture
 
-Or for local development:
+| Layer | Role |
+|-------|------|
+| **Ground Truth** | `MEMORY.md` + `auto-*.md` overflow files |
+| **Vector Index** | `memory.vec.sqlite` (derived; cosine scan + MMR; default top-3, min relevance 0.4) |
+| **Sidecar** | Separate Node process over UDS JSONL (`query`, `reindex`, `ping`) |
+| **Preflight** | QueryIntent → Sidecar → Fallback to MEMORY.md → silent empty inject |
 
-```json
-{
-  "packages": ["./extensions/pi-memory"]
-}
-```
+### Write paths
 
-Pi reads `package.json` > `pi.extensions` and auto-loads the extension via [jiti](https://github.com/unjs/jiti) (TypeScript, no build step needed).
+1. **`/remember`** — sync user-authored append
+2. **Compaction** — dual-purpose summary → `appendFromCompaction` (Compact Delta for subagents)
+3. **Consolidate** — OR trigger (overflow ≥12 / 7 days / daily 03:00 cron)
 
-## Quick Start
+**Diagnostics:** **`/memory-status`** in session, or **`pi-memory status`** on the CLI.
 
-```bash
-# 1. Install the package
-pi install npm:@chendpoc/pi-memory
+**Shutdown Queue** — `session_shutdown` appends metadata to `.memory_shutdown_queue.jsonl`; **`pi-memory maintenance`** (or `drain-shutdown-queue`) ingests missed facts offline.
 
-# 2. Train a memory bundle from your session history
-npx pi-memory train --full
+### Data directory
 
-# 3. Restart Pi --- memory is now active
-# Try asking: "What projects have I worked on?"
-```
+All memory artifacts share one root directory (the **memory agent dir**):
 
-After training, Pi will:
-- Show `status: ready, mode: local_graph` when you type `/memory`
-- Automatically inject past context when you ask relationship questions
-- Let the LLM call `memory_recall` for explicit lookups
+| File | Purpose |
+|------|---------|
+| `MEMORY.md` | Ground truth |
+| `auto-*.md` | Overflow entries |
+| `memory.vec.sqlite` | Vector index (derived) |
+| `memory.sock` | Sidecar UDS |
 
-## How It Works
+Resolution order (extension and CLI):
 
-```
-Pi session files (.jsonl)
-    |
-    v
-Trainer (regex or LLM extraction)
-    |
-    v
-graph.json bundle (entities + relations + events)
-    |
-    v
-LocalGraphQuerier (in-memory graph query)
-    |
-    v
-memory_recall tool / implicit preflight injection
-```
+1. `--agent-dir` / `PI_MEMORY_AGENT_DIR` — explicit override
+2. Default — `~/.pi/pi-memory-data` (no env required)
 
-### Query Backends
+### MEMORY.md format
 
-The service automatically selects the best available backend:
+Canonical scaffold (`templates/MEMORY.md.example`):
 
-| Priority | Backend | Requires |
-|----------|---------|----------|
-| 1 | **LocalGraphQuerier** (in-process) | bundle only |
-| 2 | **FTS5 + keyword fallback** | `better-sqlite3` (optional) |
+- Title `# Memory` + HTML comment describing entry format
+- Four sections: **Preferences**, **Conventions**, **Findings**, **Todos**
+- Entries: `- [user] note <!-- id:... user ts:... -->` (via `/remember`) or `- note <!-- id:... ts:... -->`
+- 150-line cap; overflow spills to `auto-*.md`
 
-The default backend is LocalGraphQuerier --- pure TypeScript, no external dependencies.
+**Initialization** (never overwrites a non-empty file):
 
-## Commands
+1. `pnpm install` → `postinstall` seeds `MEMORY.md` in the memory agent dir
+2. First Pi session → `MemoryStore.ensureInitialized()` on `session_start`
+3. Manual: `pi-memory init`
 
-| Command | Description |
-|---------|-------------|
-| `/memory` | Show service status, query mode, and bundle info |
+## Setup
 
-## CLI
+1. Install dependencies and build:
 
 ```bash
-# Train a bundle from session history
-npx pi-memory train --full                    # full rebuild
-npx pi-memory train                           # incremental (only new sessions)
-npx pi-memory train --extractor llm           # use LLM for deeper extraction
-npx pi-memory train --extractor llm --model deepseek/deepseek-v4-flash
-
-# Query the knowledge graph
-npx pi-memory query '{"mode":"direct_relation","anchor_mentions":["Alice"]}'
+pnpm install
+pnpm build
+```
 
-# Service diagnostics
-npx pi-memory health
-npx pi-memory status
+2. Enable as a Pi extension (see `package.json` → `pi.extensions`).
 
-# Manage bundles
-npx pi-memory install-bundle ./path/to/bundle
+3. Optional: copy [`.env.example`](./.env.example) to `~/.pi/agent/pi-memory.env` and configure embedder / helper LLM.
 
-# Rebuild FTS5 search index
-npx pi-memory index
+## Environment
 
-# Continuous training (watch mode)
-npx pi-memory train --watch
-```
+| Variable | Purpose |
+|----------|---------|
+| `PI_MEMORY_AGENT_DIR` | Memory data root (see [Data directory](#data-directory)) |
+| `PI_MEMORY_EMBEDDER` | `hash` (default, offline) \| `ollama` \| `openai` |
+| `PI_MEMORY_HELPER_MODEL` | Helper LLM for QueryIntent + consolidate |
+| `PI_MEMORY_PREFLIGHT_BUDGET_MS` | Preflight shared budget (default 800ms: ~240 intent + ~560 sidecar) |
+| `PI_MEMORY_REINDEX_DEBOUNCE_MS` | Debounced reindex after writes |
+| `PI_MEMORY_DEBUG` | `1` enables debug stderr logs (preflight timings) |
 
-## Flags
+See [`.env.example`](./.env.example) for full list.
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--memory-helper-model` | LLM model for intent detection and rerank | `deepseek/deepseek-v4-flash` |
+## CLI
 
 ```bash
-pi --memory-helper-model deepseek/deepseek-v4-flash
+pi-memory init
+pi-memory status
+pi-memory maintenance --cron --verbose
+pi-memory consolidate --force --verbose
+pi-memory drain-shutdown-queue --verbose
 ```
 
-## Data Layout
+`maintenance` runs **consolidate → drain-shutdown-queue** in one cron window (recommended for OS schedulers).  
+`status` prints MEMORY.md, sidecar, and vector index diagnostics (colored on TTY stderr).  
+Set `PI_MEMORY_DEBUG=1` for preflight timing logs during agent sessions.
 
-```
-~/.pi/
-├── memory/
-│   ├── current/              # active bundle (symlink)
-│   │   ├── manifest.json
-│   │   └── graph.json        # entities, edges, events
-│   ├── bundles/              # historical bundles
-│   ├── sessions.db           # FTS5 search index
-│   └── .train_marker         # incremental training timestamp
-├── agent/sessions/           # Pi session files (.jsonl)
-└── MEMORY.md                 # persistent notes (memory_append target)
-```
-
-## Programmatic API
-
-```typescript
-import {
-  MemoryService,
-  defaultMemoryConfig,
-  trainBundle,
-  LocalGraphQuerier,
-  createLLMFactExtractor,
-  createStandaloneLLMClient,
-  rerankWithLLM,
-} from "@chendpoc/pi-memory";
-
-// --- Query the graph directly ---
-const querier = new LocalGraphQuerier("/Users/you/.pi/memory");
-querier.load();
-const result = querier.query({
-  mode: "direct_relation",
-  anchor_mentions: ["Alice"],
-});
-
-// --- Train a bundle ---
-const result = await trainBundle({
-  sessionsDir: "~/.pi/agent/sessions",
-  bundleRoot: "~/.pi/memory",
-  full: true,
-});
-
-// --- Train with LLM extraction ---
-const client = createStandaloneLLMClient("deepseek/deepseek-v4-flash");
-const extractor = createLLMFactExtractor({ client, batchSize: 10 });
-await trainBundle({ extractOpts: { llmExtractor: extractor } });
-
-// --- Use as Pi extension ---
-import piMemory from "@chendpoc/pi-memory/extension";
-export default piMemory;
-```
-
-## Architecture
-
-| Module | Purpose |
-|--------|---------|
-| `src/pi-extension.ts` | Pi ExtensionAPI entry point |
-| `src/local/graphQuery.ts` | In-process graph query engine |
-| `src/adapters/piComplete.ts` | LLM adapter via `@earendil-works/pi-ai/compat` |
-| `src/service.ts` | Service lifecycle and query routing |
-| `src/trainer/` | Session loader, fact extraction, entity resolution, bundle builder |
-| `src/fallback/` | FTS5 index, keyword search, LLM rerank |
-| `src/preflight/` | Intent detection, private memory render/inject/strip |
-| `src/tools/` | `memory_recall` and `memory_append` tool definitions |
-
-## Implicit Preflight
-
-On every LLM call, the `context` event:
+Templates: [`templates/`](./templates/) (launchd, crontab, schtasks).
 
-1. Detects memory-relevant intents via regex (Chinese/English/Japanese relationship patterns)
-2. Optionally calls a helper LLM (`compile_memory_intents` forced tool_use)
-3. Queries the graph for matching entities/relations
-4. Injects a `<private_memory>` block into the user message (deep copy, not persisted to session)
-5. Results are cached per agent loop to avoid redundant queries during multi-tool turns
+## Docs
 
-## Peer Dependencies
-
-These are provided by the Pi host and should not be bundled:
-
-- `@earendil-works/pi-agent-core`
-- `@earendil-works/pi-ai`
-- `@earendil-works/pi-coding-agent`
-- `typebox`
-
-## Optional Dependencies
-
-- `better-sqlite3` --- enables FTS5 session search index (graceful degradation if absent)
-
-## Development
-
-```bash
-npm install
-npm run build
-npm test          # 129 tests
-npm run typecheck
-```
+- [sidecar-local-memory-design.md](./sidecar-local-memory-design.md) — full design
+- [kocoro-memory-pi-agent-guide.md](./kocoro-memory-pi-agent-guide.md) — Kocoro → Pi translation
+- [UBIQUITOUS_LANGUAGE.md](./UBIQUITOUS_LANGUAGE.md) — domain glossary
 
 ## License
 

package/UBIQUITOUS_LANGUAGE.md

@@ -0,0 +1,81 @@
+# Ubiquitous Language
+
+> pi-memory 扩展的领域术语表。实现与文档以本表 canonical 名称为准。
+
+## Storage
+
+| Term | Definition | Aliases to avoid |
+| ---- | ---------- | ---------------- |
+| **Ground Truth** | The durable cross-session fact store: `MEMORY.md` plus overflow `auto-*.md` files. | memory.db, chat backup |
+| **Vector Index** | A derived SQLite file (`memory.vec.sqlite`) holding embeddings for episodic retrieval. | memory.db, sqlite-vec ANN |
+| **Memory Entry** | One bullet fact in Ground Truth under Preferences, Conventions, Findings, or Todos. | note, fact, bullet |
+| **Overflow File** | An `auto-*.md` spill file created when `MEMORY.md` exceeds the line cap. | auto file, spill |
+
+## Read path
+
+| Term | Definition | Aliases to avoid |
+| ---- | ---------- | ---------------- |
+| **Preflight** | Best-effort retrieval and injection before the main model sees each user message. | memory recall, pre-fetch |
+| **QueryIntent** | Structured retrieval hints (what/who/where or raw_query) extracted by a helper LLM. | search intent |
+| **Memory Cap** | Session-scoped static summary of Ground Truth injected without episodic query. | turnMemoryIndex, static cap |
+| **Episodic Preflight** | QueryIntent → Sidecar query → optional Fallback for query-dependent recall. | full preflight |
+| **Fallback** | Silent read of Ground Truth when Sidecar returns nothing or errors. | md fallback |
+| **Private Memory** | The `<private_memory>` block prefixed to in-flight user messages only. | injected context |
+
+## Write path
+
+| Term | Definition | Aliases to avoid |
+| ---- | ---------- | ---------------- |
+| **Memory Export** | The cross-session facts section inside a dual-purpose compact summary. | memoryQueue, export block |
+| **Compact Delta** | New Memory Export facts filtered against existing Ground Truth before append (subagent). | Stage1, shutdown extract |
+| **Dual-Purpose Summary** | One LLM compact output with Session Context and Memory Export sections. | compact summary |
+| **Consolidate** | Periodic LLM merge/dedupe of Ground Truth; not a source of new facts. | GC, merge |
+| **Shutdown Queue** | Append-only JSONL file (`.memory_shutdown_queue.jsonl`) of session metadata on shutdown; drained by `pi-memory maintenance`. | session enqueue pipeline |
+
+## Infrastructure
+
+| Term | Definition | Aliases to avoid |
+| ---- | ---------- | ---------------- |
+| **Sidecar** | Separate Node process for embed, vector scan, MMR, and reindex over UDS. | tlm, daemon |
+| **JSONL Framing** | One JSON object per line over UDS IPC. | NDJSON, ndjson |
+| **Index Generation** | Monotonic counter bumped on reindex; invalidates query cache. | indexGeneration |
+| **onSyncToSidecar** | Callback fired after Ground Truth writes to schedule debounced reindex. | onDirty |
+| **onConsolidateCheck** | Callback fired after writes to schedule debounced consolidate evaluation. | onDirty |
+
+## Session types
+
+| Term | Definition | Aliases to avoid |
+| ---- | ---------- | ---------------- |
+| **Root Session** | A top-level Pi agent session without a parent session header. | main session |
+| **Subagent Session** | A forked session whose header includes `parentSession` or `parent_session`. | child session, fork |
+
+## Relationships
+
+- **Ground Truth** is the source; the **Vector Index** is derived and may lag.
+- **Preflight** reads **Ground Truth** via **Sidecar** first, then **Fallback**.
+- **Root Session** runs **Episodic Preflight** plus **Memory Cap** each turn; **Subagent Session** runs **Memory Cap** only.
+- **Memory Export** from compaction flows through **Compact Delta** for **Subagent Session**, then **appendIfAbsent**.
+- **Shutdown Queue** records metadata only; it does not write **Ground Truth**.
+- **Consolidate** rewrites **Ground Truth** and triggers **onSyncToSidecar**.
+
+## Example dialogue
+
+> **Dev:** "When a **Subagent Session** compacts, do we run **Episodic Preflight** on its turns?"
+>
+> **Domain expert:** "No. Subagents get **Memory Cap** at **session_start** and skip **Episodic Preflight**. New durable facts still arrive via **Memory Export**, but **Compact Delta** filters out anything already in parent **Ground Truth**."
+>
+> **Dev:** "What happens on **session_shutdown**?"
+>
+> **Domain expert:** "We append one line to the **Shutdown Queue**—session file, parent path, reason. No LLM on shutdown. **`pi-memory maintenance`** drains the queue offline (after consolidate), reusing **Compact Delta** rules for subagents."
+>
+> **Dev:** "If **Sidecar** is down, does **Preflight** fail?"
+>
+> **Domain expert:** "It **Fallback**s to **Ground Truth** or **Private Memory** stays empty. The user never sees an error."
+
+## Flagged ambiguities
+
+- **memory.db** was used for the vector file — canonical name is **Vector Index** file `memory.vec.sqlite`.
+- **sqlite-vec** implied ANN search — MVP uses **better-sqlite3 + full-table cosine scan**; ANN is future work.
+- **NDJSON / ndjson** — canonical term is **JSONL Framing** (one JSON object per line).
+- **memoryQueue / onDirty / Stage1** — replaced by **appendFromCompaction**, **onSyncToSidecar**, and **Compact Delta**.
+- **MVP chunking**：**1 Memory Entry = 1+ vector chunks**；超过 `PI_MEMORY_CHUNK_MAX_CHARS`（默认 512）按段落/句界拆分，`chunk_id = entry.id` 或 `entry.id#N`；embed 文本带 `[Section]` 前缀。Ground Truth 仍为 1 bullet = 1 entry。

package/dist/adapters/embed/factory.d.ts

@@ -0,0 +1,7 @@
+import type { Embedder } from "./types.js";
+export declare function createEmbedder(env?: import("../../config/env.js").PiMemoryEnv): Embedder;
+export declare function getEmbedder(): Embedder;
+/** @internal test hook */
+export declare function resetEmbedderForTests(): void;
+export type { Embedder } from "./types.js";
+//# sourceMappingURL=factory.d.ts.map

package/dist/adapters/embed/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/adapters/embed/factory.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,wBAAgB,cAAc,CAAC,GAAG,4CAAoB,GAAG,QAAQ,CA4BhE;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAGtC;AAED,0BAA0B;AAC1B,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/adapters/embed/factory.js

@@ -0,0 +1,44 @@
+import { DEFAULT_HASH_EMBED_DIM } from "../../constants/env.js";
+import { readPiMemoryEnv, resolveEmbedDim } from "../../config/env.js";
+import { createHashEmbedder } from "./hash.js";
+import { createOllamaEmbedder } from "./ollama.js";
+import { createOpenAiEmbedder } from "./openai.js";
+let cachedEmbedder;
+export function createEmbedder(env = readPiMemoryEnv()) {
+    switch (env.embedder) {
+        case "openai": {
+            if (!env.openaiApiKey) {
+                throw new Error("PI_MEMORY_EMBEDDER=openai requires PI_MEMORY_OPENAI_API_KEY or OPENAI_API_KEY");
+            }
+            const dim = resolveEmbedDim(env.openaiEmbedModel, env.embedDimOverride);
+            return createOpenAiEmbedder({
+                apiKey: env.openaiApiKey,
+                model: env.openaiEmbedModel,
+                dim,
+                timeoutMs: env.httpTimeoutMs,
+            });
+        }
+        case "ollama": {
+            const dim = resolveEmbedDim(env.ollamaEmbedModel, env.embedDimOverride);
+            return createOllamaEmbedder({
+                baseUrl: env.ollamaBaseUrl,
+                model: env.ollamaEmbedModel,
+                dim,
+                timeoutMs: env.httpTimeoutMs,
+            });
+        }
+        default: {
+            const dim = env.embedDimOverride ?? DEFAULT_HASH_EMBED_DIM;
+            return createHashEmbedder(dim);
+        }
+    }
+}
+export function getEmbedder() {
+    cachedEmbedder ??= createEmbedder();
+    return cachedEmbedder;
+}
+/** @internal test hook */
+export function resetEmbedderForTests() {
+    cachedEmbedder = undefined;
+}
+//# sourceMappingURL=factory.js.map

package/dist/adapters/embed/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/adapters/embed/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,IAAI,cAAoC,CAAC;AAEzC,MAAM,UAAU,cAAc,CAAC,GAAG,GAAG,eAAe,EAAE;IACpD,QAAQ,GAAG,CAAC,QAAQ,EAAE,CAAC;QACrB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAC;YACnG,CAAC;YACD,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACxE,OAAO,oBAAoB,CAAC;gBAC1B,MAAM,EAAE,GAAG,CAAC,YAAY;gBACxB,KAAK,EAAE,GAAG,CAAC,gBAAgB;gBAC3B,GAAG;gBACH,SAAS,EAAE,GAAG,CAAC,aAAa;aAC7B,CAAC,CAAC;QACL,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACxE,OAAO,oBAAoB,CAAC;gBAC1B,OAAO,EAAE,GAAG,CAAC,aAAa;gBAC1B,KAAK,EAAE,GAAG,CAAC,gBAAgB;gBAC3B,GAAG;gBACH,SAAS,EAAE,GAAG,CAAC,aAAa;aAC7B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,GAAG,GAAG,GAAG,CAAC,gBAAgB,IAAI,sBAAsB,CAAC;YAC3D,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,cAAc,KAAK,cAAc,EAAE,CAAC;IACpC,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,qBAAqB;IACnC,cAAc,GAAG,SAAS,CAAC;AAC7B,CAAC"}

package/dist/adapters/embed/hash.d.ts

@@ -0,0 +1,3 @@
+import type { Embedder } from "./types.js";
+export declare function createHashEmbedder(dim: number): Embedder;
+//# sourceMappingURL=hash.d.ts.map

package/dist/adapters/embed/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/adapters/embed/hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAuBxD"}

package/dist/adapters/embed/hash.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+import { normalizeEmbedding } from "./normalize.js";
+export function createHashEmbedder(dim) {
+    const embedSync = (text) => {
+        const vec = new Float32Array(dim);
+        const digest = createHash("sha256").update(text).digest();
+        for (let i = 0; i < dim; i++) {
+            const byte = digest[i % digest.length];
+            const sign = digest[(i + 7) % digest.length] & 1 ? 1 : -1;
+            vec[i] = sign * (byte / 255);
+        }
+        return normalizeEmbedding(vec);
+    };
+    return {
+        provider: "hash",
+        model: "hash/dev",
+        dim,
+        async embed(text) {
+            return embedSync(text);
+        },
+        async embedBatch(texts) {
+            return texts.map(embedSync);
+        },
+    };
+}
+//# sourceMappingURL=hash.js.map

package/dist/adapters/embed/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../../src/adapters/embed/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,SAAS,GAAG,CAAC,IAAY,EAAgB,EAAE;QAC/C,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAE,CAAC;YACxC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3D,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,UAAU;QACjB,GAAG;QACH,KAAK,CAAC,KAAK,CAAC,IAAI;YACd,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,KAAK;YACpB,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/embed/normalize.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeEmbedding(vec: Float32Array): Float32Array;
+export declare function assertEmbeddingDim(embedding: Float32Array, expectedDim: number, label: string): void;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/adapters/embed/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/adapters/embed/normalize.ts"],"names":[],"mappings":"AAAA,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAMlE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIpG"}

package/dist/adapters/embed/normalize.js

@@ -0,0 +1,15 @@
+export function normalizeEmbedding(vec) {
+    let norm = 0;
+    for (let i = 0; i < vec.length; i++)
+        norm += vec[i] * vec[i];
+    norm = Math.sqrt(norm) || 1;
+    for (let i = 0; i < vec.length; i++)
+        vec[i] /= norm;
+    return vec;
+}
+export function assertEmbeddingDim(embedding, expectedDim, label) {
+    if (embedding.length !== expectedDim) {
+        throw new Error(`${label} dimension mismatch: expected ${expectedDim}, got ${embedding.length}`);
+    }
+}
+//# sourceMappingURL=normalize.js.map

package/dist/adapters/embed/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/adapters/embed/normalize.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,kBAAkB,CAAC,GAAiB;IAClD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,IAAI,GAAG,CAAC,CAAC,CAAE,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;IAC/D,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAE,IAAI,IAAI,CAAC;IACrD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAuB,EAAE,WAAmB,EAAE,KAAa;IAC5F,IAAI,SAAS,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,iCAAiC,WAAW,SAAS,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACnG,CAAC;AACH,CAAC"}

package/dist/adapters/embed/ollama.d.ts

@@ -0,0 +1,8 @@
+import type { Embedder } from "./types.js";
+export declare function createOllamaEmbedder(opts: {
+    baseUrl: string;
+    model: string;
+    dim: number;
+    timeoutMs: number;
+}): Embedder;
+//# sourceMappingURL=ollama.d.ts.map

package/dist/adapters/embed/ollama.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.d.ts","sourceRoot":"","sources":["../../../src/adapters/embed/ollama.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAW3C,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,QAAQ,CA8BX"}

package/dist/adapters/embed/ollama.js

@@ -0,0 +1,31 @@
+import { postJson } from "../http.js";
+import { assertEmbeddingDim, normalizeEmbedding } from "./normalize.js";
+function joinUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, "")}${path}`;
+}
+export function createOllamaEmbedder(opts) {
+    const url = joinUrl(opts.baseUrl, "/api/embed");
+    const embedRemote = async (texts) => {
+        const json = await postJson(url, { model: opts.model, input: texts.length === 1 ? texts[0] : texts }, { timeoutMs: opts.timeoutMs });
+        return json.embeddings.map((row, index) => {
+            const embedding = normalizeEmbedding(new Float32Array(row));
+            assertEmbeddingDim(embedding, opts.dim, `Ollama ${opts.model} row ${index}`);
+            return embedding;
+        });
+    };
+    return {
+        provider: "ollama",
+        model: opts.model,
+        dim: opts.dim,
+        async embed(text) {
+            const [embedding] = await embedRemote([text]);
+            return embedding;
+        },
+        async embedBatch(texts) {
+            if (texts.length === 0)
+                return [];
+            return embedRemote(texts);
+        },
+    };
+}
+//# sourceMappingURL=ollama.js.map

package/dist/adapters/embed/ollama.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../../src/adapters/embed/ollama.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAQxE,SAAS,OAAO,CAAC,OAAe,EAAE,IAAY;IAC5C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAKpC;IACC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAEhD,MAAM,WAAW,GAAG,KAAK,EAAE,KAAe,EAA2B,EAAE;QACrE,MAAM,IAAI,GAAG,MAAM,QAAQ,CACzB,GAAG,EACH,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EACnE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAC9B,CAAC;QAEF,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YACxC,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5D,kBAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,IAAI,CAAC,KAAK,QAAQ,KAAK,EAAE,CAAC,CAAC;YAC7E,OAAO,SAAS,CAAC;QACnB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,QAAQ;QAClB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,CAAC,KAAK,CAAC,IAAI;YACd,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9C,OAAO,SAAU,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,KAAK;YACpB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;YAClC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/embed/openai.d.ts

@@ -0,0 +1,8 @@
+import type { Embedder } from "./types.js";
+export declare function createOpenAiEmbedder(opts: {
+    apiKey: string;
+    model: string;
+    dim: number;
+    timeoutMs: number;
+}): Embedder;
+//# sourceMappingURL=openai.d.ts.map

package/dist/adapters/embed/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/adapters/embed/openai.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,QAAQ,CAgCX"}

package/dist/adapters/embed/openai.js

@@ -0,0 +1,30 @@
+import { postJson } from "../http.js";
+import { assertEmbeddingDim, normalizeEmbedding } from "./normalize.js";
+export function createOpenAiEmbedder(opts) {
+    const embedRemote = async (texts) => {
+        const json = await postJson("https://api.openai.com/v1/embeddings", { model: opts.model, input: texts }, {
+            headers: { Authorization: `Bearer ${opts.apiKey}` },
+            timeoutMs: opts.timeoutMs,
+        });
+        return json.data
+            .sort((a, b) => a.index - b.index)
+            .map((row) => {
+            const embedding = normalizeEmbedding(new Float32Array(row.embedding));
+            assertEmbeddingDim(embedding, opts.dim, `OpenAI ${opts.model}`);
+            return embedding;
+        });
+    };
+    return {
+        provider: "openai",
+        model: opts.model,
+        dim: opts.dim,
+        async embed(text) {
+            const [embedding] = await embedRemote([text]);
+            return embedding;
+        },
+        async embedBatch(texts) {
+            return embedRemote(texts);
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/adapters/embed/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../../src/adapters/embed/openai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAOxE,MAAM,UAAU,oBAAoB,CAAC,IAKpC;IACC,MAAM,WAAW,GAAG,KAAK,EAAE,KAAe,EAA2B,EAAE;QACrE,MAAM,IAAI,GAAG,MAAM,QAAQ,CACzB,sCAAsC,EACtC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EACnC;YACE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE,EAAE;YACnD,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CACF,CAAC;QAEF,OAAO,IAAI,CAAC,IAAI;aACb,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACjC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACX,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;YACtE,kBAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAChE,OAAO,SAAS,CAAC;QACnB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,QAAQ;QAClB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,CAAC,KAAK,CAAC,IAAI;YACd,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9C,OAAO,SAAU,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,KAAK;YACpB,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/embed/types.d.ts

@@ -0,0 +1,9 @@
+import type { EmbedderProvider } from "../../config/env.js";
+export type Embedder = {
+    provider: EmbedderProvider;
+    model: string;
+    dim: number;
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/embed/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/adapters/embed/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3C,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACtD,CAAC"}

package/dist/adapters/embed/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/adapters/embed/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/embed/types.ts"],"names":[],"mappings":""}

package/dist/adapters/http.d.ts

@@ -0,0 +1,13 @@
+export type PostJsonOptions = {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export declare class HttpRequestError extends Error {
+    readonly url: string;
+    readonly status: number;
+    readonly body: string;
+    constructor(url: string, status: number, body: string);
+}
+export declare function postJson<T>(url: string, body: unknown, opts?: PostJsonOptions): Promise<T>;
+//# sourceMappingURL=http.d.ts.map