recallnest 1.4.1 → 2.2.1

package/.github/workflows/ci.yml

@@ -1,28 +0,0 @@
-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

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

package/CHANGELOG.md

@@ -1,51 +0,0 @@
-# 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/DEMO.md

@@ -1,94 +0,0 @@
-# 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

@@ -1,89 +0,0 @@
-# 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

@@ -1,75 +0,0 @@
-# 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/OPERATIONS.md

@@ -1,59 +0,0 @@
-# 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.

package/ROADMAP.md

@@ -1,198 +0,0 @@
-# RecallNest Roadmap
-
-> Vision: a shared memory layer for Claude Code, Codex, and Gemini CLI that gets more useful over time.
-
-RecallNest is no longer best described as "local transcript search." The real target is stricter:
-
-- one memory layer shared by the three terminals
-- stable context that survives across windows
-- memory that becomes more reusable, not just larger
-
-This roadmap reflects that direction.
-
-## The Core Problem
-
-Today, most coding agents have weak continuity:
-
-- past context is scattered across tools
-- a new window often behaves like a reset
-- search is passive, so memory works only when explicitly invoked
-- transcript archives are large, but high-value memories are sparse
-
-RecallNest exists to close that gap without giving up local control.
-
-What matters first is this: opening another window should not erase stable context about the user, projects, patterns, and past solutions.
-
-## Status Summary
-
-### Already Done
-
-- Shared local LanceDB index
-- MCP server for Claude Code, Gemini CLI, and Codex
-- HTTP API for custom agents
-- Ingestion from existing transcripts and memory files
-- Hybrid retrieval: vector + BM25 + reranking
-- 6-category memory classification
-- Tier-aware decay and access reinforcement
-- Brief and pin assets re-indexed into recall
-- Session checkpoints for active work state
-- `resume_context` composition for fresh windows
-- Continuity eval harness with seed cases and baseline reports
-- Setup scripts, diagnostics, and debugging UI
-- Explicit evidence -> durable promotion with provenance and `canonicalKey`
-- Conflict candidates, review, audit, escalation, merge resolution, and audit export
-
-### Current Gap
-
-RecallNest is already usable as a three-terminal continuity layer, but a few operating gaps remain.
-
-The main gaps are:
-
-- continuity eval still depends on the latest live checkpoint in one case
-- conflict review is strong in CLI, but scheduled audit/export is still missing
-- high-signal memory extraction and promotion quality can still improve
-
-## Phase 1: Shared Memory Foundation
-
-Status: done
-
-Goal: make all three terminals use the same local memory base.
-
-Delivered:
-
-- one local index shared by Claude Code, Codex, and Gemini CLI
-- MCP integration scripts for the three terminals
-- HTTP API for agent frameworks
-- multi-source ingest pipeline
-
-## Phase 2: Searchable Recall Engine
-
-Status: done
-
-Goal: make the memory base actually retrievable.
-
-Delivered:
-
-- hybrid retrieval
-- retrieval profiles
-- memory categories
-- tiering and decay
-- explain, distill, brief, and pin flows
-
-## Phase 3: Cross-Window Continuity Layer
-
-Status: usable in the current stage
-
-Goal: a fresh window should recall stable context without depending on the user to restate it.
-
-Delivered:
-
-- session checkpoints for active work state
-- `resume_context` for fresh windows
-- context composition that prefers stable background over blindly replaying the last topic
-- managed continuity rules installed by setup for Claude Code, Codex, and Gemini CLI
-
-Remaining work:
-
-- isolate eval from live checkpoint drift
-- keep measuring instruction-driven startup continuity across the three terminals
-- expand checkpoint-aware continuity coverage and keep tracking trendlines
-
-Likely interfaces:
-
-- `resume_context`
-- `checkpoint_session`
-- startup-oriented MCP and API flows
-
-## Phase 4: High-Signal Memory Capture
-
-Status: usable in the current stage
-
-Goal: store more useful memory and less raw transcript residue.
-
-Delivered:
-
-- `store_memory` for MCP
-- dedicated workflow-pattern capture for durable `patterns`
-- structured capture endpoints for non-MCP agents
-- explicit evidence promotion into durable memory
-- boundary guards for `evidence / durable / session`
-- conflict handling when new durable candidates disagree with existing canonical owners
-
-Remaining work:
-
-- improve extraction toward durable facts, preferences, entities, cases, and patterns
-- better dedup before low-value text reaches the index
-
-Likely interfaces:
-
-- `store_memory` for MCP
-- structured capture endpoints for non-MCP agents
-
-## Phase 5: Memory Boundary and Conflict Operations
-
-Status: usable in the current stage
-
-Goal: stop durable memory from drifting silently and make conflicts operable in the terminal.
-
-Delivered:
-
-- `promote_memory` with provenance and `canonicalKey`
-- conflict candidates instead of silent overwrite
-- terminal conflict review: `list / show / resolve`
-- conflict advice, clusters, audit, escalation, and `merge`
-- audit export snapshots in markdown or JSON
-
-Remaining work:
-
-- scheduled audit / export for recurring review
-- stronger merge and promotion heuristics
-
-Likely interfaces:
-
-- `resolve_conflict`
-- `audit_conflicts`
-- `escalate_conflicts`
-- CLI `recallnest conflicts ...`
-
-## Phase 6: Self-Evolution Engine
-
-Status: planned
-
-Goal: make memory quality improve over time.
-
-Planned work:
-
-- memory consolidation for merge-style categories
-- duplicate cleanup for append-style categories
-- gap detection from weak or failed searches
-- promotion suggestions for memories that should become persistent rules
-- better tier maintenance and archival policies
-
-Likely endpoints:
-
-- `POST /v1/consolidate`
-- `GET /v1/gaps`
-- MCP `consolidate_memory`
-
-## Phase 7: Product Polish
-
-Status: ongoing
-
-Goal: make RecallNest easier to trust, measure, and operate.
-
-Planned work:
-
-- continuity eval isolation from live checkpoints
-- broader continuity-focused evals and benchmarks
-- stronger docs around achieved vs planned capabilities
-- health and quality summaries in CLI
-- cleaner setup for long-running background usage
-
-## Principles
-
-- Local-first: all memory stays on your machine
-- Three-terminal first: Claude Code, Codex, and Gemini CLI are the immediate focus
-- Continuity over transcript hoarding: useful memory matters more than raw volume
-- Agent-agnostic at the interface layer: HTTP API and MCP remain the public surface
-- Measured evolution: use evals before tuning retrieval or memory policies