recallnest 1.4.1

package/.claude-plugin/CLAUDE.md

@@ -0,0 +1,29 @@
+# RecallNest Memory Plugin
+
+RecallNest is a local-first shared memory layer backed by LanceDB. It stores and recalls context across sessions, terminals, and agents (Claude Code, Codex, Gemini CLI).
+
+**Prerequisite**: Requires [Bun](https://bun.sh) runtime. On first start, dependencies install automatically.
+
+## Tool Quick Reference
+
+| When | Tool | Purpose |
+|------|------|---------|
+| Session opens, user says continue/接着/上个窗口 | `resume_context` | Load stable context, latest checkpoint, recent cases |
+| Before answering about prior work / known facts | `search_memory` | Targeted fact/pattern recall (2-3 key nouns) |
+| After solving something significant | `store_memory` or `store_case` | Persist durable knowledge |
+| Before closing a window with unfinished work | `checkpoint_session` | Save current state for next session |
+| After discovering a reusable workflow | `store_workflow_pattern` | Persist as durable pattern |
+| Memory feels stale or conflicted | `consolidate_memories` | Merge near-duplicates (dry-run by default) |
+
+## Continuity Rules
+
+- If the user says `continue`, `继续`, `接着`, `刚才`, `上个窗口`, `不要让我重复前情`, or asks where you stopped / what to do next — call `resume_context` before any Bash, Read, or repo exploration.
+- If the user starts a concrete task in an active project or asks for prior implementation detail — do lightweight RecallNest recovery before repo exploration even without an explicit `continue`.
+- Do not substitute `git status`, `git log`, or reading local docs for `resume_context`. Local inspection can validate current code state only **after** continuity has been recovered.
+- When `scope` or `sessionId` is known, pass it into recall tools instead of relying on global recall.
+- If `resume_context` returns a resolved scope or checkpoint scope, reuse that same scope in follow-up `search_memory`, `brief_memory`, `pin_memory` calls.
+- If recalled context mentions repo state (modified files, pending push), treat it as **handoff context only** — do not restate as current state without verifying in this window.
+- Before leaving a window with resumable work, call `checkpoint_session`. Do not include repo state claims unless you actually inspected the repo this window.
+- Use `store_memory` for durable profile, preference, entity, or case knowledge.
+- Use `store_workflow_pattern` for reusable multi-step workflows.
+- If the user explicitly corrects a continuity miss, fix the workflow and call `workflow_observe` with `outcome: corrected`.

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "AliceLJY",
+  "owner": {
+    "name": "Alice Jin Ye"
+  },
+  "metadata": {
+    "description": "RecallNest — shared memory layer for Claude Code, Codex, and Gemini CLI",
+    "homepage": "https://github.com/AliceLJY/recallnest"
+  },
+  "plugins": [
+    {
+      "name": "recallnest",
+      "version": "1.4.1",
+      "source": "./",
+      "description": "Local-first memory system: store, search, and recall context across sessions and terminals. Powered by LanceDB with hybrid retrieval."
+    }
+  ]
+}

package/.env.example

@@ -0,0 +1,3 @@
+# Embedding API key (required)
+# Jina: https://jina.ai/ — get a free API key
+JINA_API_KEY=your_jina_api_key_here

package/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install
+
+      - name: Setup config
+        run: cp config.json.example config.json
+
+      - name: Doctor (CI mode)
+        run: bun run src/cli.ts doctor --ci
+
+      - name: TypeScript check
+        run: bun build src/cli.ts --target bun --no-bundle --outdir /tmp/check 2>&1 || true

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "recallnest": {
+      "type": "stdio",
+      "command": "bash",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/start-server.sh"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## v1.3.1 — Upstream Sync (2026-03-12)
+
+Synced with [CortexReach/memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) master (v1.1.0-beta.6+).
+
+### Changed
+
+- **Retriever**: Added `source` field to `RetrievalContext` — access reinforcement now only fires on manual retrieval, preventing auto-recall from strengthening noise memories (synced from upstream beta.2 design).
+- **Noise filter**: Added Chinese meta-question patterns (`你记得`, `记不记得`, `还记得…吗`, `上次…说`, `之前…提到`) and diagnostic artifact filter (synced from upstream beta.3).
+- **README**: Updated upstream credit link from `win4r/memory-lancedb-pro` to `CortexReach/memory-lancedb-pro`, added CortexReach team acknowledgement.
+
+## v1.2.0 — First Distributable Release (2026-03-08)
+
+The goal of this release: a new user can go from `git clone` to first search result in 15 minutes.
+
+### New
+
+- **`lm doctor`** — one-command pre-flight check for Bun, config, API key, data directory, transcript paths, and index health. Supports `--ci` mode for GitHub Actions.
+- **`lm demo`** — run sample queries to see RecallNest in action before writing your own.
+- **`config.json.example`** — ships with absolute `~/.recallnest/data/lancedb` path. New users copy this instead of editing the tracked config.
+- **GitHub Actions CI** — runs `doctor --ci` and TypeScript check on every push.
+- **Ingest pre-validation** — embedding API is tested before processing any files. Invalid Jina key now fails fast with a clear message instead of crashing mid-ingest.
+
+### Changed
+
+- **README rewritten** — added Prerequisites table (Bun + Jina key), 5-step quickstart with expected output, Troubleshooting section.
+- **Gemini support marked "coming soon"** — README, config example, and doctor all honestly reflect that Gemini CLI sessions are encrypted protobuf and not yet parseable. The `lm ingest` command prints a clear skip message instead of silently failing.
+- **Config path robustness** — default `dbPath` changed from relative `./data/lancedb` to absolute `~/.recallnest/data/lancedb` in config example. Auto-detect failure messages now include the user's actual home path.
+- **`config.json` untracked** — added to `.gitignore` so user config is not overwritten by `git pull`.
+
+### Fixed
+
+- Auto-detect hint in `doctor` now shows a real example path based on the current user's home directory.
+- `findConfigPath()` error message now suggests `cp config.json.example config.json` when the example file exists.
+
+## v1.1.0 — Hybrid Retrieval + MCP + UI (2026-02)
+
+- Hybrid retrieval: LanceDB vector + BM25 keyword search with configurable weights
+- Retrieval profiles: `default`, `writing`, `debug`, `fact-check`
+- MCP server with 9 tools: search, explain, distill, brief, pin, list assets/pins, export, stats
+- Local web workbench UI at `http://localhost:4317`
+- Multi-source ingest: Claude Code transcripts, Codex sessions, Gemini sessions, markdown notes
+- Asset system: pin, brief, export with re-indexing
+- Time-aware scoring with configurable decay
+
+## v1.0.0 — Initial Release (2026-01)
+
+- Basic vector search over Claude Code transcripts
+- LanceDB storage with Jina embeddings
+- CLI interface

package/CLAUDE.md

@@ -0,0 +1,42 @@
+# RecallNest 项目规则
+
+## 1. 技术栈约束（强制）
+
+- **运行时：Bun**。禁止使用 `npm`、`yarn`、`pnpm`，所有命令走 `bun`
+- **语言：TypeScript strict**。禁止 `any` 类型，复杂接口提取到独立类型文件
+- **向量存储：LanceDB**。不引入其他向量数据库
+- **嵌入模型：Jina v5**。不替换嵌入方案
+- **MCP 协议：`@modelcontextprotocol/sdk`**。MCP tools 统一走 `registerTool()`
+
+## 2. 编码规范
+
+- 新增 MCP tool 必须同时写测试（`src/__tests__/`）
+- 禁止生成带 `// TODO` 或 `// placeholder` 的半成品代码——缺信息就停下来问
+- 修改已有 tool 的 schema 前，先确认调用方兼容性
+- 脚本放 `scripts/`，不在 `src/` 之外创建业务 `.ts` 文件
+
+## 3. Agent 行为准则
+
+- **写代码后必须自己跑测试**：执行 `bun test`，读报错，自主修复，直到全绿才交付
+- 实现新功能前，先输出分步计划并等待确认，再进入执行阶段
+- 任务颗粒度过大时，主动拆分子任务逐步推进，不要一口气撸完然后崩溃
+- 禁止用未验证的 `git status` 结果写入 checkpoint
+
+## 4. Git Push 规则（重要！）
+
+- **所有 push 只推 origin**（`trihippo/recallnest`）
+- **绝对不要 push 到 upstream**（`CortexReach/memory-lancedb-pro`）—— 那是上游公开仓库，推了等于暴露私有改造
+- **绝对不要 push 到 public**（`AliceLJY/recallnest`）—— 除非用户明确要求
+- 默认 `git push` 即可（默认推 origin）
+- 需要给上游提 PR 时，走 fork + PR 流程，不直接 push
+
+## 5. Feature Flag
+
+- `RECALLNEST_MULTI_VECTOR=true` — 多向量 L0/L1/L2 检索
+- `RECALLNEST_KG_MODE=true` — KG 三元组提取 + 图遍历
+
+## 6. 测试基线
+
+- 改完代码必须跑 `bun test`，全量通过才能 commit
+- 当前基线：643 tests / 0 fail
+- 新增功能必须配套测试，基线只能涨不能降

package/DEMO.md

@@ -0,0 +1,94 @@
+# RecallNest 30-Second Demo
+
+Use this script when you want to explain RecallNest fast on GitHub, X, Telegram, or in a live screen recording.
+
+## Demo Goal
+
+Show three things in one pass:
+
+| What to prove | What the viewer should understand |
+|------|------|
+| Recall | old AI conversations can be found quickly |
+| Explainability | hits are not opaque |
+| Reusability | useful context can become a long-lived asset |
+
+## Fast Setup
+
+```bash
+cd /Users/anxianjingya/recallnest
+bun run src/ui-server.ts
+```
+
+Open:
+
+```text
+http://localhost:4317
+```
+
+## Recommended Demo Query
+
+Use:
+
+```text
+telegram bridge
+```
+
+Reason:
+
+| Why this query works | Result |
+|------|------|
+| already appears in the current dataset | likely to return hits immediately |
+| has operational context | good for showing explainability |
+| already has assets | good for showing reuse |
+
+## 30-Second Talk Track
+
+### Version A
+
+```text
+This is RecallNest, a local-first memory workbench for AI conversations.
+It turns Claude Code, Codex, Gemini, and notes into a recall layer.
+I can search an old topic, inspect why it matched, then pin useful context back into memory so it can be recalled again later.
+The same memory layer is exposed through MCP, so an agent can use it and I can still verify it in the UI.
+```
+
+### Version B
+
+```text
+RecallNest is not just transcript search.
+It lets me search, explain, distill, and reuse past AI conversations.
+The key idea is that useful hits do not disappear again: I can turn them into assets and feed them back into recall.
+```
+
+## Demo Click Path
+
+| Step | UI action | What to say |
+|------|------|------|
+| 1 | show the loaded `telegram bridge` query | "This starts from a real transcript topic." |
+| 2 | click `Search` | "I can recall the relevant conversation history." |
+| 3 | click `Details` on one result | "The hit is inspectable, not a black box." |
+| 4 | click `Pin` or `Brief` | "Useful context becomes a reusable asset." |
+| 5 | switch to `Assets` | "Assets stay visible and can be recalled later." |
+
+## Screenshot Rules
+
+| Rule | Why |
+|------|------|
+| keep the browser crop tight | the product, not Chrome, should dominate the frame |
+| show real hits in the result area | empty states spread poorly |
+| keep `Trace Output` collapsed unless you are explaining it | it distracts from the main product story |
+| prefer one strong screenshot over many average ones | easier to share and understand |
+
+## If The UI Opens Empty
+
+Check:
+
+1. the server is running
+2. the current dataset was ingested
+3. the page has been refreshed after startup
+
+If needed, re-run:
+
+```bash
+bun run src/ui-server.ts
+```

package/EVAL.md

@@ -0,0 +1,89 @@
+# RecallNest Eval Memo
+
+This file is the operator memo for improving retrieval quality without relying on intuition.
+
+## Why this exists
+
+RecallNest will keep evolving with:
+- upstream retrieval changes from `memory-lancedb-pro`
+- local tuning for your own workflows
+- new asset behavior (`pin`, `brief`, cleanup rules)
+
+Without a repeatable eval, it is impossible to tell whether recall actually improved.
+
+## Core files
+
+| File | Purpose |
+|------|---------|
+| `eval/cases.json` | real-world recall cases to protect |
+| `src/eval.ts` | eval runner |
+| `eval/reports/` | saved baselines to compare across upgrades |
+
+## What to evaluate
+
+Use queries that matter in real usage:
+- bot / bridge maintenance
+- OpenClaw memory architecture
+- writing style and user preference recall
+- visual style preference recall
+- AWS / config operations
+
+Important:
+- prefer the wording the operator actually types
+- do not invent a cleaner label if the real query is messier but more common
+- if `aws ssh` is what gets used in practice, benchmark `aws ssh`, not `aws bot config`
+- abstract, summarized queries are valid benchmarks if that is how the operator naturally searches
+- protect both query styles: exact operational wording and high-level conceptual wording
+
+Each case should define:
+- `query`
+- `profile`
+- optional `scope`
+- `expectAny`
+- `expectAll`
+- `expectScopePrefixes`
+- optional `forbid`
+
+## Recommended workflow
+
+### Before changing retrieval
+
+Run:
+
+```bash
+bun run src/eval.ts --output eval/reports/latest.md
+```
+
+If the change is important, also save a dated snapshot:
+
+```bash
+bun run src/eval.ts --output eval/reports/2026-03-06-baseline.md
+```
+
+### After changing retrieval
+
+Run the same eval again and compare:
+- pass count
+- average score
+- top scopes
+- top snippet quality
+
+## What counts as a good change
+
+Good:
+- relevant source scopes move up
+- user preference memories stay stable
+- bridge / ops / config queries become easier to recover
+- `pin` and `brief` behave differently on purpose
+
+Bad:
+- asset recursion comes back
+- old noisy `brief` objects dominate retrieval
+- exact operational queries stop surfacing recent config changes
+- writing/style queries drift away from user preference memories
+
+## Maintenance note
+
+Whenever a new recurring workflow appears, add it to `eval/cases.json`.
+
+That turns “I hope this still works” into “I can prove it still works.”

package/FAILURES.md

@@ -0,0 +1,75 @@
+# RecallNest Failure Notebook
+
+Use this file to record misses, weak hits, and noisy hits.
+
+Do not rely on memory when retrieval quality changes. Add an entry, then update `eval/cases.json` if the failure should become a permanent benchmark.
+
+## How To Use
+
+| Step | Action |
+|------|------|
+| 1 | Record the exact query you ran |
+| 2 | Note the mode, scope, and surface (`UI`, `MCP`, or `CLI`) |
+| 3 | Write what you expected to see |
+| 4 | Write what actually happened |
+| 5 | Make one concrete hypothesis, not five vague ones |
+| 6 | After a fix, record whether the issue moved into `eval/cases.json` |
+
+## Entry Template
+
+```md
+## YYYY-MM-DD - short_name
+
+| Field | Value |
+|------|------|
+| Query | `...` |
+| Profile | `default / writing / debug / fact-check` |
+| Scope | `...` |
+| Surface | `UI / MCP / CLI` |
+| Expected | ... |
+| Actual | ... |
+| Failure Type | `miss / weak hit / noisy hit / asset pollution / bad ranking` |
+| Hypothesis | ... |
+| Fix | ... |
+| Eval Case Added | `yes / no` |
+```
+
+## Current Known Weak Spots
+
+| Query family | Current issue | Status |
+|------|------|------|
+| `aws ssh` | needs to stay strong because this is the real operator wording | watch |
+| abstract relationship queries | must keep working without exact keywords | watch |
+| asset-heavy topics | old briefs can pollute recall if asset hygiene is ignored | mitigated, keep watching |
+
+## Entries
+
+## 2026-03-06 - aws_query_wording
+
+| Field | Value |
+|------|------|
+| Query | `aws bot config` vs `aws ssh` |
+| Profile | `debug` |
+| Scope | `cc / codex / gemini / memory` |
+| Surface | `UI` |
+| Expected | the AWS access path should be easy to recover using the wording the operator naturally types |
+| Actual | `aws ssh` returns stronger and more directly useful hits than `aws bot config` |
+| Failure Type | `bad ranking` |
+| Hypothesis | the earlier eval case used an artificial wording closer to a label than a real operator query |
+| Fix | replace the eval case with `aws ssh` and treat operator wording as the benchmark source of truth |
+| Eval Case Added | `yes` |
+
+## 2026-03-06 - working_relationship_positive
+
+| Field | Value |
+|------|------|
+| Query | `我们相处态度` |
+| Profile | `default` |
+| Scope | `cc / codex / gemini / memory` |
+| Surface | `UI` |
+| Expected | abstract relationship and collaboration preferences should still surface the right context |
+| Actual | user reported the result felt right; eval later passed at `73%`, which means it works but is still weaker than exact operational queries |
+| Failure Type | `weak hit / positive signal` |
+| Hypothesis | semantic recall is working for summarized wording, but abstract preference queries still need stronger ranking and cleaner memory prioritization |
+| Fix | keep this query as a protected eval case and treat it as a primary target for future retrieval tuning |
+| Eval Case Added | `yes` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AliceLJY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/OPERATIONS.md

@@ -0,0 +1,59 @@
+# RecallNest Operations
+
+This file is the short operator memo for common actions.
+
+## Open The UI
+
+### Manual
+
+```bash
+cd /Users/anxianjingya/recallnest
+bun run src/ui-server.ts
+```
+
+Then open:
+
+```text
+http://localhost:4317
+```
+
+### Ask Codex
+
+Use either of these:
+
+- `帮我启动 RecallNest UI`
+- `帮我打开 RecallNest 记忆工作台`
+- `帮我把 RecallNest 的本地界面跑起来`
+
+Expected result:
+- local UI server starts
+- browser target is `http://localhost:4317`
+
+## Quick Intent Phrases
+
+### Search
+- `帮我在 RecallNest 里搜 telegram bridge`
+- `帮我查一下过去关于 OpenClaw memory 的记录`
+
+### Distill
+- `帮我把 OpenClaw 记忆系统蒸馏成 briefing`
+
+### Brief
+- `帮我把这个主题做成一个 brief asset`
+
+### Assets
+- `帮我打开 Assets 视图`
+- `帮我看一下有哪些 memory assets`
+
+### Cleanup
+- `帮我检查有没有 dirty briefs`
+- `帮我清理旧的脏 brief`
+
+## Product Position
+
+RecallNest should be operated primarily through:
+
+1. MCP
+2. UI
+
+CLI is an implementation layer, not the main product surface.