@memory-river/core 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Hsi431
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,222 @@
+# @memory-river/core
+
+**Three-tier memory for agents — a working recap that fades, durable facts that persist, and the full transcript it can always go back and re-read.**
+
+[繁體中文](./README.zh-TW.md)
+
+Most "agent memory" is a vector store with a save button: one flat pile of embeddings you write to and search. Memory River is a memory *system* modeled on how memory actually works — it keeps information at **three timescales**, retrieves it in **two passes**, lets memories **metabolize** over time, and can trace anything it distilled back to the exact turns it came from. You inject your own embedding and LLM providers; the engine is host-independent.
+
+> `0.2.x` is an early API. Review upgrades before adopting a new minor release.
+
+## The idea: three timescales of memory
+
+When a conversation grows past a watermark, Memory River doesn't just truncate the old turns — it **distills** them into memory at three timescales:
+
+- **Short term — the session capsule.** A compact recap of what just happened, injected at the top of the next prompt so the model keeps the thread after old turns are cut. It starts at low health and **metabolizes fast** — this is working memory for *this* session, not a fact store. The capsule is domain-adaptive: a coding session gets a structured task summary; a casual conversation gets a natural-language recap.
+- **Medium term — distilled notes.** Alongside each capsule, a handful of granular, self-contained facts are extracted and written to the store as ordinary memories. They start at full health and **persist** — this is what `recall` surfaces days later.
+- **Long term — the raw transcript.** Every turn is archived verbatim with a byte-offset index, and the session capsule records the exact turns it summarized — so nothing is ever truly lost to compression.
+
+## Retrieval in two passes
+
+1. **Coarse recall (automatic, cheap).** Before a model turn, `assembleContext` injects the top couple of relevant memories. Always on.
+2. **Rehydrate (precise, on demand).** A lossy memory carries pointers back to its source turns; the agent calls `rehydrate` to pull the **exact original turns** — verbatim numbers, names, dates — by entry-id, time window, or keyword.
+
+The common case stays cheap (you don't reload the whole conversation every turn), but precise detail is never more than one hop away. This is also what makes Memory River **auditable**: every distilled claim can be traced to the source turns that produced it.
+
+## Memory that metabolizes
+
+Memories aren't write-once rows. They **live**: health decays over time and refreshes on access; a newer fact **supersedes** a close older one; contradictions are **flagged and deprecated** instead of silently coexisting; a nightly pass **merges** redundant memories; dead memories are cleaned up through a trash-protected path. Core categories, high-importance facts, and skill capsules are protected from decay — so the store stays relevant instead of growing into noise.
+
+## How it's built
+
+| Subsystem | What it does | Module |
+| --- | --- | --- |
+| Dual-tier store + WAL | RAM-dir (e.g. tmpfs) for hot reads, data-dir for durability, write-ahead log with crash recovery | `store/store-v4` |
+| Distillation pipeline | Old turns are summarized into a capsule + granular notes, written through an async inbox so writes never block the conversation | `distill/concentrator-adapter` + `pipeline/inbox-watcher` |
+| Transcript + rehydrate | Verbatim turn archive with a byte-offset `.idx`; recover exact turns by entry-id, time, or keyword | `transcript/` |
+| Hybrid retrieval | Vector + full-text BM25, RRF fusion, optional local rerank (CRAG-style accept/partial/reject, tuned recall-safe), EntitySynergyMerger (NER fragment rescue), Structured-Slot dedup, causal-chain context expansion | `retrieval/retriever-v4` |
+| Knowledge graph | Triple (subject–relation–object) store with vector + FTS entity search, used to expand hook/query coverage | `store/graph-store` |
+| Memory metabolism | Health decays over time, refreshes on access; dead memories cleaned up through a trash-protected path | `lifecycle/cleanup-engine` |
+| Night consolidation | Periodic offline pass that merges and compresses related memories | `lifecycle/night-consolidation` |
+| Associative hooks | Memories can carry trigger keywords that fire related recalls; a feedback loop reweights hooks by hit quality | `cognition/hooks-engine` |
+| Causal + conflict | Newer facts supersede close older ones; contradictions are flagged and deprecated with a `supersededBy` chain | `cognition/causal-engine` + `conflict-detector` |
+| Structured slots | Extracts structured params (slotKey/slotValue) at write time with a version chain; retrieval returns only the latest active per slot | `pipeline/inbox-watcher` + `retrieval/retriever-v4` |
+| Global Working Memory (GWM) | Tracks the long-conversation task; embedding drift detection nudges the agent back on topic | `cognition/global-working-memory` |
+| Skill capsules v2 | Explicitly saved procedures with progressive disclosure: a one-line index is injected, full steps load on demand | `engine` + `skills/` |
+| Ralph Loop | Context circuit-breaker: on repeated failures it trims/truncates context and injects warnings to keep context from blowing up | `cognition/ralph-core` |
+| Observability | Every subsystem writes best-effort stats rows (`subsystem_effectiveness`, `status_audit_log`, …) you can audit later | throughout |
+
+Everything above is in the code today — this README intentionally describes nothing aspirational.
+
+## Requirements
+
+- Node.js 20
+- An `EmbeddingProvider` (a ready-made `OllamaEmbedding` is included)
+- An `LlmClient` (any function that turns a prompt into text — see Quick Start)
+- Two writable directories (`dataDir` for durability, `ramDir` for the hot tier — tmpfs if you have it, any disk dir works)
+
+Optional native deps degrade gracefully: `nodejieba` (CJK tokenization, falls back to character split) and `@xenova/transformers` (local reranker, falls back to pass-through).
+
+## Installation
+
+```bash
+npm install @memory-river/core
+```
+
+In this monorepo:
+
+```bash
+npm ci
+npm run build -w @memory-river/core
+```
+
+## Quick Start
+
+The repository's [`example-cli`](../example-cli/src/cli.ts) (~110 lines) is a complete non-OpenClaw integration using Ollama for both embeddings and chat:
+
+```bash
+ollama pull hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF
+ollama pull qwen3:8b
+npm run build -ws
+
+node packages/example-cli/dist/cli.js remember "The deployment window is Friday at 18:00."
+node packages/example-cli/dist/cli.js recall "When is deployment?"
+node packages/example-cli/dist/cli.js chat
+```
+
+The equivalent core setup:
+
+```ts
+import {
+  createMemoryRiver,
+  OllamaEmbedding,
+  type LlmClient,
+} from '@memory-river/core';
+
+const ollamaUrl = 'http://localhost:11434';
+
+const llm: LlmClient = {
+  async generate(prompt, opts) {
+    const response = await fetch(`${ollamaUrl}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        model: 'qwen3:8b',
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: opts?.maxTokens,
+      }),
+    });
+    if (!response.ok) throw new Error(`LLM request failed: ${response.status}`);
+    const body = await response.json() as any;
+    return body.choices?.[0]?.message?.content ?? '';
+  },
+};
+
+const embedder = new OllamaEmbedding({
+  provider: 'ollama',
+  apiKey: '',
+  model: 'hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF',
+  dimensions: 1024,
+  ollamaUrl,
+});
+
+const river = createMemoryRiver(
+  {
+    dataDir: '/var/lib/my-agent/memory-river',
+    ramDir: '/var/lib/my-agent/memory-river/ram',
+    autoRecall: true,
+  },
+  { embedder, llm },
+);
+
+await river.start();
+try {
+  await river.remember('The deployment window is Friday at 18:00.', {
+    category: 'fact',
+    importance: 0.8,
+  });
+  const results = await river.recall('When is deployment?', 5);
+  console.log(results);
+} finally {
+  await river.stop();
+}
+```
+
+`start()` initializes the engine, starts the inbox watcher, and schedules maintenance. `stop()` stops watchers and timers and shuts down the memory store.
+
+## API
+
+`createMemoryRiver(config, deps)` returns:
+
+| API | Purpose |
+| --- | --- |
+| `start()` / `stop()` | Engine lifecycle. |
+| `remember(text, opts?)` | Store a memory with optional category, importance, metadata. |
+| `recall(query, limit?)` | Ranked `MemorySearchResult` records from hybrid retrieval. |
+| `assembleContext(messages, session?)` | Inject relevant memories (and the skill index) into a message list before a model turn. |
+| `skills.save / load / search / list` | Skill capsules v2 — see below. |
+| `rehydrate(request)` | Read archived transcript entries by IDs, time range, or keyword. |
+| `archiveTranscript(session, messages)` | Append host messages to the transcript archive. |
+| `compactSessionFile(session, opts?)` | Compact a host session file when `SessionFileAccess` resolves one. |
+| `gwm.on/off/status/update` | Global Working Memory state (goal tracking + drift detection). |
+| `maintenance.runCleanup()` / `runNightConsolidation()` | Trigger maintenance manually. |
+
+`MemoryRiverConfig` requires `dataDir` and `ramDir`; everything else (`embedding`, `retrieval`, `cleanup`, `health`, `hooks`, `causalEngine`, `concentration`, `autoRecall`, `driftThreshold`, …) is optional and merged with defaults.
+
+## Skill Capsules v2
+
+Skills are procedures your agent explicitly saves — the system never auto-generates them:
+
+```ts
+await river.skills.save({
+  name: 'git-release',
+  summary: 'Tag and push a release the standard way',
+  triggers: ['release', 'tag a version'],
+  steps: ['Run the test suite', 'git tag -s vX.Y.Z', 'git push --tags', 'Draft release notes'],
+});
+```
+
+- **Progressive disclosure**: `assembleContext` injects only a one-line index (`【git-release】triggers… → skill_load("git-release")`); full steps cost zero tokens until the agent calls `skills.load`.
+- **Honest usage stats**: only `load` increments `usageCount` — being injected doesn't count as being used.
+- **Lifecycle**: skills decay 4× slower than ordinary memories and heal on every load; unused ones eventually fade out instead of polluting the index forever.
+- **Deterministic quality gate**: malformed definitions are rejected with every violation listed at once — no LLM judging, no silent fixes.
+
+## Dependency Ports
+
+The host owns external services. Required: `embedder`, `llm`. Optional: `logger`, `notifier`, `sessionFiles`.
+
+```ts
+interface EmbeddingProvider {
+  embed(text: string, mode?: 'store' | 'query'): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+  getDimensions(): number;
+  healthCheck?(): Promise<boolean>;
+}
+
+interface LlmClient {
+  generate(prompt: string, opts?: { purpose?: string; maxTokens?: number }): Promise<string>;
+}
+```
+
+Provider selection, retries, fallback, and rate limiting belong in your `LlmClient` — core deliberately does not ship a multi-provider fallback chain.
+
+`Logger` defaults to console. `Notifier` defaults to no-op. Without `SessionFileAccess`, transcript archiving and rehydration still work; only `compactSessionFile()` becomes a no-op.
+
+## Porting to Another Agent Host
+
+1. Pick writable `dataDir` + `ramDir`.
+2. Implement `EmbeddingProvider` (or use `OllamaEmbedding`).
+3. Implement `LlmClient` (~20 lines for any OpenAI-compatible endpoint).
+4. `createMemoryRiver(...)`, `start()` on host startup, `stop()` on shutdown.
+5. Expose `remember` / `recall` (and optionally `skills.save` / `skills.load`) as host tools.
+
+That's a working integration — `example-cli` is exactly this and fits in ~110 lines. Steps 6–9 are optional layers: pass conversations through `assembleContext`, archive transcripts for `rehydrate`, wire `SessionFileAccess` for session-file compaction, connect `Logger`/`Notifier`.
+
+## Persistence Notes
+
+LanceDB-backed dual-tier storage plus a WAL. Inserts are WAL-protected before the call returns; replay is idempotent and a failed replay preserves the log for the next attempt. The package does not claim exactly-once recovery or zero data loss — treat the data directory as application state and back it up accordingly.
+
+## License
+
+Apache-2.0 © 2026 Hsi431. Use, modify, embed, and ship freely under the permissive
+Apache 2.0 terms. See the repository-root [LICENSE](../../LICENSE).

package/README.zh-TW.md

@@ -0,0 +1,186 @@
+# @memory-river/core
+
+**給 agent 的三層記憶 — 會褪色的工作摘要、會留存的事實、以及永遠能回頭重讀的完整原文。**
+
+[English](./README.md)
+
+大多數「agent 記憶」就是一個 vector store 加一顆儲存鍵:一坨平的 embedding,你往裡寫、往裡搜。Memory River 是一套**模擬真實記憶運作**的記憶*系統* — 它把資訊保存在**三種時間尺度**、用**兩段式**檢索、讓記憶隨時間**代謝**,而且任何被蒸餾出來的東西都能**追溯回它來自哪幾句原文**。embedding 和 LLM 由你注入,引擎本身不綁任何宿主框架。
+
+> `0.2.x` 是早期 API,升版前請先看變更。
+
+## 核心概念:三種時間尺度的記憶
+
+當對話長過水位線,Memory River 不是把舊對話截掉就算了 — 它把舊對話**蒸餾**成三種時間尺度的記憶:
+
+- **短期 — session 膠囊。** 剛剛發生了什麼的精簡前情提要,注入下一個 prompt 頂端,讓模型在舊對話被裁切後仍接得上脈絡。它起始健康度低、**代謝得快** — 這是*這次 session* 的工作記憶,不是事實庫。膠囊會依領域自適應:寫程式的 session 給結構化任務摘要,閒聊給自然語言前情提要。
+- **中期 — 蒸餾筆記。** 每顆膠囊旁邊,會抽出幾條顆粒化、可獨立理解的事實,當作一般記憶寫進庫裡。它們起始滿血、**會留存** — 幾天後 `recall` 撈到的就是這些。
+- **長期 — 原始 transcript。** 每一句對話都逐字歸檔,帶 byte-offset 索引;膠囊會記下它摘要了哪幾句確切原文 — 所以壓縮不會真的丟失任何東西。
+
+## 兩段式檢索
+
+1. **粗召回(自動、便宜)。** 模型回合前,`assembleContext` 注入最相關的少數幾條記憶。永遠開著。
+2. **Rehydrate(精確、按需)。** 失真的記憶會帶著回指原文的指標;agent 呼叫 `rehydrate`,用 entry-id、時間窗或關鍵字撈回**確切的原始對話** — 逐字的數字、人名、日期。
+
+常態很便宜(你不必每回合重載整段對話),但精確細節永遠只差一跳。這也讓 Memory River **可稽核**:每一條蒸餾出的結論,都能追回產生它的那幾句原文。
+
+## 會代謝的記憶
+
+記憶不是寫一次就不動的列。它們**會活**:健康度隨時間衰減、被存取就回血;新事實會**取代**相近的舊事實;矛盾會被**標記並 deprecated**,而不是默默並存;夜間有一趟把冗餘記憶**合併**;歸零的記憶走 trash 保護路徑清掉。核心類別、高重要性事實、技能膠囊免於衰減 — 所以記憶庫保持相關,而不是長成一堆雜訊。
+
+## 怎麼蓋起來的
+
+| 子系統 | 做什麼 | 模組 |
+| --- | --- | --- |
+| 雙層儲存 + WAL | RAM 目錄(可放 tmpfs)做熱讀、資料目錄做持久層、write-ahead log 含當機恢復 | `store/store-v4` |
+| 蒸餾管線 | 舊對話被摘成膠囊 + 顆粒化筆記,經非同步 inbox 寫入 — 寫入永不阻塞對話 | `distill/concentrator-adapter` + `pipeline/inbox-watcher` |
+| Transcript + rehydrate | 逐字原文歸檔 + byte-offset `.idx`;用 entry-id、時間、關鍵字撈回確切原文 | `transcript/` |
+| Hybrid 檢索 | 向量 + 全文 BM25、RRF 融合、可選的本地 cross-encoder rerank(CRAG 式 accept/partial/reject,調在 recall 安全端)、EntitySynergyMerger(NER 碎片搶救)、Structured Slot 去重、因果鏈上下文擴展 | `retrieval/retriever-v4` |
+| 知識圖譜 | 三元組(subject–relation–object)儲存,向量 + FTS 實體搜尋,供鉤子做語意查詢擴展 | `store/graph-store` |
+| 記憶代謝 | 健康度隨時間衰減、被存取就回血;歸零的記憶走 trash 保護路徑清掉 | `lifecycle/cleanup-engine` |
+| 夜間整理 | 週期性離線合併、壓縮相關記憶 | `lifecycle/night-consolidation` |
+| 聯想鉤子 | 記憶可帶觸發關鍵字,命中時連帶喚起相關記憶;命中成效有回饋閉環動態調權 | `cognition/hooks-engine` |
+| 因果 + 衝突 | 新事實取代相近舊事實;矛盾被標記並 deprecated 並記 `supersededBy` 追溯鏈 | `cognition/causal-engine` + `conflict-detector` |
+| Structured Slot | 寫入時抽結構化參數(slotKey/slotValue)+ 版本鏈;檢索時同 slot 只回最新 active | `pipeline/inbox-watcher` + `retrieval/retriever-v4` |
+| 全局工作記憶 (GWM) | 追蹤長對話主任務,embedding 漂移偵測,偏題時注入提醒拉回 | `cognition/global-working-memory` |
+| 技能膠囊 v2 | 顯式儲存的程序性知識,漸進式揭露:平時只注入一行索引,要用才載入完整步驟 | `engine` + `skills/` |
+| Ralph Loop | context 斷路器:連續失敗時修剪 / 截斷 context、注入警告,防 context 爆掉 | `cognition/ralph-core` |
+| 可觀測性 | 每個子系統 best-effort 寫統計列(`subsystem_effectiveness`、`status_audit_log`…),事後可稽核 | 遍布全系統 |
+
+以上每一項都是現在 code 裡真的有的 — 這份 README 刻意不描述任何「願景」。
+
+## 需求
+
+- Node.js 20
+- 一個 `EmbeddingProvider`(內建 `OllamaEmbedding` 可直接用)
+- 一個 `LlmClient`(任何「prompt 進、文字出」的函式 — 見 Quick Start)
+- 兩個可寫目錄(`dataDir` 持久層、`ramDir` 熱層 — 有 tmpfs 用 tmpfs,一般磁碟目錄也行)
+
+可選的原生依賴都能優雅降級:`nodejieba`(中日韓斷詞,缺了退回逐字切)、`@xenova/transformers`(本地 reranker,缺了直通)。
+
+## 安裝
+
+```bash
+npm install @memory-river/core
+```
+
+在這個 monorepo 裡:
+
+```bash
+npm ci
+npm run build -w @memory-river/core
+```
+
+## Quick Start
+
+repo 裡的 [`example-cli`](../example-cli/src/cli.ts)(約 110 行)就是一個完整的非 OpenClaw 整合,embedding 和聊天都走 Ollama:
+
+```bash
+ollama pull hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF
+ollama pull qwen3:8b
+npm run build -ws
+
+node packages/example-cli/dist/cli.js remember "老闆喜歡手沖咖啡"
+node packages/example-cli/dist/cli.js recall "咖啡"
+node packages/example-cli/dist/cli.js chat
+```
+
+等價的 core 寫法(完整版見英文 README,只差字串語言):
+
+```ts
+import { createMemoryRiver, OllamaEmbedding } from '@memory-river/core';
+
+const river = createMemoryRiver(
+  {
+    dataDir: '/var/lib/my-agent/memory-river',
+    ramDir: '/var/lib/my-agent/memory-river/ram',
+    autoRecall: true,
+  },
+  { embedder, llm },  // 你注入的 EmbeddingProvider 與 LlmClient
+);
+
+await river.start();
+try {
+  await river.remember('老闆喜歡手沖咖啡', { category: 'preference', importance: 0.8 });
+  console.log(await river.recall('咖啡', 5));
+} finally {
+  await river.stop();
+}
+```
+
+`start()` 初始化引擎、啟動 inbox watcher、排程維護;`stop()` 停掉 watcher 與 timer 並關閉儲存層。
+
+## API
+
+`createMemoryRiver(config, deps)` 回傳:
+
+| API | 用途 |
+| --- | --- |
+| `start()` / `stop()` | 引擎生命週期。 |
+| `remember(text, opts?)` | 存記憶,可帶 category、importance、metadata。 |
+| `recall(query, limit?)` | hybrid 檢索的排序結果。 |
+| `assembleContext(messages, session?)` | 模型回合前,把相關記憶(與技能索引)注入訊息列。 |
+| `skills.save / load / search / list` | 技能膠囊 v2,見下節。 |
+| `rehydrate(request)` | 按 ID、時間範圍或關鍵字撈回歸檔的逐字稿。 |
+| `archiveTranscript(session, messages)` | 把宿主訊息寫入逐字稿歸檔。 |
+| `compactSessionFile(session, opts?)` | 有 `SessionFileAccess` 時壓縮宿主 session 檔。 |
+| `gwm.on/off/status/update` | Global Working Memory(目標追蹤 + 漂移偵測)。 |
+| `maintenance.runCleanup()` / `runNightConsolidation()` | 手動觸發維護。 |
+
+`MemoryRiverConfig` 只有 `dataDir` 與 `ramDir` 必填,其餘(`embedding`、`retrieval`、`cleanup`、`health`、`hooks`、`causalEngine`、`concentration`、`autoRecall`、`driftThreshold`…)皆可選,與預設值合併。
+
+## 技能膠囊 v2
+
+技能是 agent **顯式儲存**的程序 — 系統永遠不會自動生成技能:
+
+```ts
+await river.skills.save({
+  name: 'git-release',
+  summary: '照標準流程打 tag 出 release',
+  triggers: ['發版', 'release'],
+  steps: ['跑完整測試', 'git tag -s vX.Y.Z', 'git push --tags', '寫 release notes'],
+});
+```
+
+- **漸進式揭露**:`assembleContext` 只注入一行索引(`【git-release】觸發: … → skill_load("git-release")`);完整步驟在 agent 呼叫 `skills.load` 之前是零 token 成本。
+- **誠實的使用統計**:只有 `load` 會 +1 `usageCount` — 被注入不算被使用。
+- **生命週期**:技能的衰減速度是一般記憶的 1/4,每次 load 回血;沒人用的技能會慢慢淡出,不會永遠佔著索引名額。
+- **確定性品質閘**:格式不合的定義會被拒收,所有違規一次列完 — 不用 LLM 評審、不做沉默修正。
+
+## 依賴 Ports
+
+外部服務由宿主擁有。必填:`embedder`、`llm`。可選:`logger`、`notifier`、`sessionFiles`。
+
+```ts
+interface EmbeddingProvider {
+  embed(text: string, mode?: 'store' | 'query'): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+  getDimensions(): number;
+  healthCheck?(): Promise<boolean>;
+}
+
+interface LlmClient {
+  generate(prompt: string, opts?: { purpose?: string; maxTokens?: number }): Promise<string>;
+}
+```
+
+供應商選擇、重試、fallback、限流都屬於你的 `LlmClient` — core 刻意不內建多供應商 fallback 鏈。
+
+`Logger` 預設走 console,`Notifier` 預設靜默。沒接 `SessionFileAccess` 時,逐字稿歸檔與 rehydrate 照常運作,只有 `compactSessionFile()` 變 no-op。
+
+## 移植到別的 agent 宿主
+
+1. 準備可寫的 `dataDir` + `ramDir`。
+2. 實作 `EmbeddingProvider`(或直接用 `OllamaEmbedding`)。
+3. 實作 `LlmClient`(任何 OpenAI 相容端點約 20 行)。
+4. `createMemoryRiver(...)`,宿主啟動時 `start()`、關閉時 `stop()`。
+5. 把 `remember` / `recall`(可加 `skills.save` / `skills.load`)掛成宿主的 tool。
+
+到這裡就是一個能用的整合 — `example-cli` 就是這五步,總共約 110 行。第 6–9 步是可選的進階層:對話過 `assembleContext`、歸檔逐字稿供 `rehydrate`、接 `SessionFileAccess` 做 session 檔壓縮、接 `Logger`/`Notifier`。
+
+## 持久性說明
+
+LanceDB 雙層儲存 + WAL。insert 在回應前先落 WAL;replay 冪等,失敗會保留 log 供下次重試。本套件**不**宣稱 exactly-once recovery 或零資料遺失 — 請把資料目錄當應用程式狀態看待,照你宿主的標準備份。
+
+## 授權
+
+Apache-2.0 © 2026 Hsi431。寬鬆條款,自由使用、修改、嵌入、出貨。詳見 repo 根目錄的 [LICENSE](../../LICENSE)。