recallnest 1.4.1 → 2.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.dockerignore +11 -0
- package/CLAUDE.md +7 -3
- package/Dockerfile +20 -0
- package/README.md +202 -130
- package/README_CN.md +263 -190
- package/ROADMAP.md +128 -81
- package/SKILL.md +250 -0
- package/assets/dashboard.png +0 -0
- package/assets/knowledge-graph.png +0 -0
- package/assets/screenshots/ui-full.png +0 -0
- package/assets/screenshots/ui-overview.png +0 -0
- package/assets/screenshots/ui-search.png +0 -0
- package/assets/ui/app.js +227 -3
- package/assets/ui/index.html +81 -11
- package/assets/ui/styles.css +178 -2
- package/bin/recallnest.mjs +62 -0
- package/bun.lock +337 -0
- package/daily-recall.sh +23 -0
- package/daily-reflections/2026-04-02.md +35 -0
- package/daily-reflections/2026-04-03.md +37 -0
- package/daily-reflections/2026-04-04.md +37 -0
- package/daily-reflections/2026-04-05.md +35 -0
- package/daily-reflections/2026-04-06.md +36 -0
- package/daily-reflections/2026-04-07.md +35 -0
- package/daily-reflections/2026-04-08.md +35 -0
- package/daily-reflections/2026-04-12.md +35 -0
- package/data/alias-map.example.json +22 -0
- package/docs/plans/2026-04-01-recall-boost.md +100 -0
- package/docs/superpowers/plans/2026-04-11-constructive-retrieval-emotion.md +1195 -0
- package/docs/superpowers/specs/2026-04-11-constructive-retrieval-emotion-design.md +398 -0
- package/glama.json +6 -0
- package/integrations/setup-all.sh +31 -0
- package/package.json +10 -3
- package/plan-philosophy-upgrades.md +363 -0
- package/plan-product-upgrades.md +155 -0
- package/plan.md +140 -0
- package/research-memory-evolution.md +440 -0
- package/research-rl-agent-memory.md +330 -0
- package/scripts/backfill-anchors.ts +130 -0
- package/scripts/diagnose-vector-search.ts +132 -0
- package/scripts/migrate-language.ts +75 -0
- package/scripts/verify-emotion-decay.ts +148 -0
- package/src/__tests__/activity-counter.test.ts +96 -0
- package/src/__tests__/admission-control.test.ts +206 -0
- package/src/__tests__/anchor-generator.test.ts +67 -0
- package/src/__tests__/babel-integration.test.ts +139 -0
- package/src/__tests__/capture-engine.test.ts +5 -3
- package/src/__tests__/cascade-forget.test.ts +1 -1
- package/src/__tests__/cc8-cc1-essential-context.test.ts +298 -0
- package/src/__tests__/circuit-breaker.test.ts +99 -0
- package/src/__tests__/cluster-consolidation.test.ts +712 -0
- package/src/__tests__/confidence-metadata.test.ts +125 -0
- package/src/__tests__/confidence-tracker.test.ts +53 -0
- package/src/__tests__/consolidation-engine.test.ts +1 -1
- package/src/__tests__/constructive-retrieval.test.ts +509 -0
- package/src/__tests__/context-collapse-renderer.test.ts +214 -0
- package/src/__tests__/context-reconstructor.test.ts +65 -0
- package/src/__tests__/conversation-importer.test.ts +692 -0
- package/src/__tests__/data-checkup.test.ts +225 -0
- package/src/__tests__/decay-exemption.test.ts +84 -0
- package/src/__tests__/dedup-guard.test.ts +39 -0
- package/src/__tests__/distill-lock.test.ts +176 -0
- package/src/__tests__/dream-pipeline.test.ts +232 -0
- package/src/__tests__/emotion-decay.test.ts +46 -0
- package/src/__tests__/emotion-detector.test.ts +56 -0
- package/src/__tests__/emotion-phase1-integration.test.ts +153 -0
- package/src/__tests__/emotion-retrieval.test.ts +56 -0
- package/src/__tests__/ethics-layer.test.ts +476 -0
- package/src/__tests__/feature-flags-integration.test.ts +54 -0
- package/src/__tests__/frequency-tracker.test.ts +113 -0
- package/src/__tests__/graph-export.test.ts +489 -0
- package/src/__tests__/interference-detector.test.ts +203 -0
- package/src/__tests__/mcp-efficiency.test.ts +288 -0
- package/src/__tests__/memory-evolution-b2-b3-e1.test.ts +243 -0
- package/src/__tests__/memory-evolution.test.ts +271 -0
- package/src/__tests__/memory-lint.test.ts +271 -0
- package/src/__tests__/narrative-architecture.test.ts +456 -0
- package/src/__tests__/pending-review.test.ts +77 -0
- package/src/__tests__/post-retrieval-filter.test.ts +178 -0
- package/src/__tests__/prediction-engine.test.ts +349 -0
- package/src/__tests__/predictive-prospective-memory.test.ts +416 -0
- package/src/__tests__/preference-slots.test.ts +99 -0
- package/src/__tests__/query-expander-alias.test.ts +89 -0
- package/src/__tests__/recall-governor.test.ts +227 -0
- package/src/__tests__/resume-context.test.ts +156 -1
- package/src/__tests__/salience-scoring.test.ts +106 -0
- package/src/__tests__/session-distiller.test.ts +611 -0
- package/src/__tests__/skill-engine.test.ts +546 -0
- package/src/__tests__/skill-promotion.test.ts +349 -0
- package/src/__tests__/supersede-chain.test.ts +154 -0
- package/src/__tests__/temporal-validity.test.ts +160 -0
- package/src/__tests__/topic-tag.test.ts +113 -0
- package/src/__tests__/trusted-memory.test.ts +828 -0
- package/src/__tests__/write-verifier.test.ts +122 -0
- package/src/access-tracker.ts +3 -2
- package/src/activity-counter.ts +109 -0
- package/src/adaptive-retrieval.ts +6 -5
- package/src/admission-control.ts +163 -0
- package/src/anchor-generator.ts +80 -0
- package/src/api-server.ts +10 -0
- package/src/audit-log.ts +122 -0
- package/src/auto-gc.ts +98 -29
- package/src/auto-recall.ts +33 -4
- package/src/capture-engine.ts +372 -23
- package/src/cascade-forget.ts +3 -2
- package/src/cli.ts +107 -5
- package/src/compat.ts +22 -0
- package/src/confidence-tracker.ts +210 -47
- package/src/conflict-store.ts +12 -3
- package/src/consolidation-engine.ts +296 -8
- package/src/context-collapse-renderer.ts +222 -0
- package/src/context-composer-stable-selection.ts +5 -1
- package/src/context-composer.ts +239 -4
- package/src/context-reconstructor.ts +404 -0
- package/src/conversation-importer.ts +441 -0
- package/src/data-checkup.ts +232 -0
- package/src/decay-engine.ts +84 -0
- package/src/distill-lock.ts +122 -0
- package/src/doctor.ts +8 -10
- package/src/dream-pipeline.ts +227 -0
- package/src/emotion-detector.ts +90 -0
- package/src/eval.ts +3 -2
- package/src/forget-engine.ts +269 -0
- package/src/frequency-tracker.ts +175 -0
- package/src/graph-export.ts +644 -0
- package/src/ingest.ts +36 -6
- package/src/interference-detector.ts +187 -0
- package/src/kg-extractor.ts +15 -24
- package/src/kg-store.ts +2 -1
- package/src/language-hook.ts +67 -0
- package/src/llm-client.ts +289 -6
- package/src/mcp-server.ts +707 -80
- package/src/memory-assets.ts +22 -5
- package/src/memory-evolution.ts +365 -0
- package/src/memory-lint.ts +429 -0
- package/src/memory-output.ts +69 -0
- package/src/memory-schema.ts +74 -2
- package/src/narrative-schema.ts +79 -0
- package/src/narrative-tagger.ts +164 -0
- package/src/pii-detector.ts +98 -0
- package/src/post-retrieval-filter.ts +76 -0
- package/src/prediction-engine.ts +253 -0
- package/src/preference-slots.ts +65 -2
- package/src/prospective-memory.ts +215 -0
- package/src/query-expander.ts +67 -0
- package/src/recall-governor.ts +183 -0
- package/src/retention-policy.ts +90 -0
- package/src/retriever.ts +828 -55
- package/src/rif.ts +34 -8
- package/src/runtime-config.ts +23 -8
- package/src/scope-inventory.ts +4 -3
- package/src/scope-policy.ts +4 -0
- package/src/session-distiller.ts +307 -0
- package/src/session-output.ts +40 -0
- package/src/session-schema.ts +37 -0
- package/src/session-store.ts +7 -2
- package/src/skill-engine.ts +208 -0
- package/src/skill-promotion.ts +293 -0
- package/src/skill-schema.ts +39 -0
- package/src/store.ts +96 -10
- package/src/topic-tag.ts +66 -0
- package/src/tracker.ts +3 -1
- package/src/ui-server.ts +80 -8
- package/src/workflow-observation-scope-review.ts +2 -1
- package/src/workflow-observation-store.ts +2 -1
- package/src/write-verifier.ts +126 -0
package/.dockerignore
ADDED
package/CLAUDE.md
CHANGED
|
@@ -24,9 +24,9 @@
|
|
|
24
24
|
|
|
25
25
|
## 4. Git Push 规则(重要!)
|
|
26
26
|
|
|
27
|
-
- **所有 push 只推 origin**(`
|
|
27
|
+
- **所有 push 只推 origin**(`AliceLJY/recallnest`)
|
|
28
28
|
- **绝对不要 push 到 upstream**(`CortexReach/memory-lancedb-pro`)—— 那是上游公开仓库,推了等于暴露私有改造
|
|
29
|
-
-
|
|
29
|
+
- `trihippo/recallnest` 已停止维护,不再推送
|
|
30
30
|
- 默认 `git push` 即可(默认推 origin)
|
|
31
31
|
- 需要给上游提 PR 时,走 fork + PR 流程,不直接 push
|
|
32
32
|
|
|
@@ -34,9 +34,13 @@
|
|
|
34
34
|
|
|
35
35
|
- `RECALLNEST_MULTI_VECTOR=true` — 多向量 L0/L1/L2 检索
|
|
36
36
|
- `RECALLNEST_KG_MODE=true` — KG 三元组提取 + 图遍历
|
|
37
|
+
- `RECALLNEST_EMOTION_SCORING=true` — Emotion detection + salience-weighted Weibull decay + arousal boost + retrieval scoring
|
|
38
|
+
- `RECALLNEST_CONSTRUCTIVE_RETRIEVAL=true` — Multi-source candidate expansion + source-map grounded reconstruction (resume default, search opt-in)
|
|
39
|
+
- `RECALLNEST_NARRATIVE_MODE=true` — Autobiographical narrative metadata layer (life-period / general-event / specific-event)
|
|
40
|
+
- `RECALLNEST_PREDICTIVE_MEMORY=true` — Heuristic-predicted prospective reminders (zero LLM, behavioral signals)
|
|
37
41
|
|
|
38
42
|
## 6. 测试基线
|
|
39
43
|
|
|
40
44
|
- 改完代码必须跑 `bun test`,全量通过才能 commit
|
|
41
|
-
- 当前基线:
|
|
45
|
+
- 当前基线:1428 tests / 0 fail
|
|
42
46
|
- 新增功能必须配套测试,基线只能涨不能降
|
package/Dockerfile
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
FROM oven/bun:1-alpine AS base
|
|
2
|
+
WORKDIR /app
|
|
3
|
+
|
|
4
|
+
# Install dependencies
|
|
5
|
+
COPY package.json ./
|
|
6
|
+
RUN bun install --frozen-lockfile 2>/dev/null || bun install
|
|
7
|
+
|
|
8
|
+
# Copy source
|
|
9
|
+
COPY src/ src/
|
|
10
|
+
COPY data/alias-map.example.json data/alias-map.example.json
|
|
11
|
+
|
|
12
|
+
# Default environment
|
|
13
|
+
ENV RECALLNEST_API_PORT=4318
|
|
14
|
+
ENV RECALLNEST_UI_PORT=4317
|
|
15
|
+
|
|
16
|
+
EXPOSE 4318 4317
|
|
17
|
+
|
|
18
|
+
# MCP stdio mode (default) — Glama introspection connects here
|
|
19
|
+
# Override with CMD ["bun","run","src/api-server.ts"] for HTTP mode
|
|
20
|
+
CMD ["bun", "run", "src/mcp-server.ts"]
|
package/README.md
CHANGED
|
@@ -12,7 +12,8 @@ A local-first memory system backed by LanceDB that turns scattered conversation
|
|
|
12
12
|
[](LICENSE)
|
|
13
13
|
[](https://bun.sh)
|
|
14
14
|
[](https://lancedb.com)
|
|
15
|
-
[](https://modelcontextprotocol.io)
|
|
16
|
+
[](https://github.com/AliceLJY/recallnest)
|
|
16
17
|
[](https://github.com/AliceLJY/recallnest)
|
|
17
18
|
|
|
18
19
|
**English** | [简体中文](README_CN.md) | [Roadmap](ROADMAP.md)
|
|
@@ -23,52 +24,22 @@ A local-first memory system backed by LanceDB that turns scattered conversation
|
|
|
23
24
|
|
|
24
25
|
## Why RecallNest?
|
|
25
26
|
|
|
26
|
-
|
|
27
|
+
Coding agents forget everything between windows. Your context — project configs, debugging decisions, entity mappings — is scattered across Claude Code, Codex, and Gemini CLI with no shared memory.
|
|
27
28
|
|
|
28
|
-
|
|
29
|
+
RecallNest solves this: **a single LanceDB-backed memory layer that all three terminals read and write**. Context stored in one window is auto-recalled in another. Sessions checkpoint on exit and resume on start. Memory decays, evolves, and self-organizes — not just raw log storage.
|
|
29
30
|
|
|
30
|
-
|
|
31
|
-
>
|
|
32
|
-
> *(switch to Codex)*
|
|
33
|
-
>
|
|
34
|
-
> **You:** "The config is at... wait, let me find it again." 😤
|
|
35
|
-
>
|
|
36
|
-
> *(next day, new Claude Code window)*
|
|
37
|
-
>
|
|
38
|
-
> **You:** "We already fixed this exact bug last week! The solution was..."
|
|
39
|
-
>
|
|
40
|
-
> **Agent:** "I don't have context about previous sessions." 🤷
|
|
31
|
+
### Benchmark: LongMemEval (ICLR 2025)
|
|
41
32
|
|
|
42
|
-
|
|
33
|
+
Evaluated on 500 questions across 6 memory abilities ([methodology](https://arxiv.org/abs/2407.15168)):
|
|
43
34
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
> *(next day, new window)*
|
|
51
|
-
>
|
|
52
|
-
> **Agent:** *(resume_context fires)* "Continuing from yesterday — the Docker port conflict was resolved by..." ✅
|
|
35
|
+
| | RecallNest | Vector-only baseline | Delta |
|
|
36
|
+
|---|---|---|---|
|
|
37
|
+
| Overall Accuracy | **29.6%** | 24.2% | **+5.4pp** |
|
|
38
|
+
| User Facts | **64.3%** | 52.9% | +11.4pp |
|
|
39
|
+
| Knowledge Update | **43.6%** | 42.3% | +1.3pp |
|
|
40
|
+
| Abstention Rate | **55.6%** | 67.8% | **-12.2pp** |
|
|
53
41
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
### What you get
|
|
57
|
-
|
|
58
|
-
| | Capability |
|
|
59
|
-
|---|---|
|
|
60
|
-
| **CC Plugin** | Install in Claude Code with one command — no manual config |
|
|
61
|
-
| **Shared Index** | One LanceDB store for Claude Code, Codex, and Gemini CLI |
|
|
62
|
-
| **Dual Interface** | MCP (stdio) for CLI tools + HTTP API for custom agents |
|
|
63
|
-
| **One-Click Setup** | Integration scripts install MCP access and continuity rules |
|
|
64
|
-
| **Hybrid Retrieval** | Vector + BM25 + reranking + Weibull decay + tier promotion |
|
|
65
|
-
| **Session Continuity** | `checkpoint_session` + `resume_context` for cross-window recovery |
|
|
66
|
-
| **Workflow Observation** | Dedicated append-only workflow health records, outside regular memory |
|
|
67
|
-
| **Structured Assets** | Pins, briefs, and distilled summaries — not just raw logs |
|
|
68
|
-
| **Smart Promotion** | Evidence → durable memory with conflict guards and merge resolution |
|
|
69
|
-
| **6 Categories** | profile, preferences, entities, events, cases, patterns |
|
|
70
|
-
| **4 Retrieval Profiles** | default, writing, debug, fact-check — tuned for different tasks |
|
|
71
|
-
| **Multi-Source Ingest** | Import existing transcripts from all three terminals |
|
|
42
|
+
Wins or ties in **all 6 categories**, with no regression. The hybrid retrieval pipeline (BM25 + vector + recency + RIF dedup) surfaces 12.2% more relevant context than vector-only search.
|
|
72
43
|
|
|
73
44
|
---
|
|
74
45
|
|
|
@@ -140,6 +111,117 @@ bun run src/cli.ts doctor
|
|
|
140
111
|
|
|
141
112
|
---
|
|
142
113
|
|
|
114
|
+
## Web UI
|
|
115
|
+
|
|
116
|
+
<p align="center">
|
|
117
|
+
<img src="assets/dashboard.png" alt="RecallNest Dashboard" width="800" />
|
|
118
|
+
<br><em>Dashboard — total count, category distribution, health score, and growth trends at a glance.</em>
|
|
119
|
+
</p>
|
|
120
|
+
|
|
121
|
+
<p align="center">
|
|
122
|
+
<img src="assets/screenshots/ui-full.png" alt="RecallNest Search Workbench" width="800" />
|
|
123
|
+
<br><em>Search Workbench — hybrid search with topic tag filtering, 4 retrieval profiles, Skills browser, and asset management.</em>
|
|
124
|
+
</p>
|
|
125
|
+
|
|
126
|
+
<p align="center">
|
|
127
|
+
<img src="assets/knowledge-graph.png" alt="RecallNest Knowledge Graph" width="800" />
|
|
128
|
+
<br><em>Knowledge Graph — interactive force-directed visualization with semantic bridges revealing cross-domain connections.</em>
|
|
129
|
+
</p>
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
bun run src/ui-server.ts
|
|
133
|
+
# → http://localhost:4317
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Core Capabilities
|
|
139
|
+
|
|
140
|
+
### Access & Setup
|
|
141
|
+
|
|
142
|
+
| Capability | Description |
|
|
143
|
+
|---|---|
|
|
144
|
+
| **CC Plugin** | Install in Claude Code with one command — no manual config |
|
|
145
|
+
| **Shared Index** | One LanceDB store for Claude Code, Codex, and Gemini CLI |
|
|
146
|
+
| **Dual Interface** | MCP (stdio) for CLI tools + HTTP API for custom agents |
|
|
147
|
+
| **One-Click Setup** | Integration scripts install MCP access and continuity rules |
|
|
148
|
+
|
|
149
|
+
### Recall & Continuity
|
|
150
|
+
|
|
151
|
+
| Capability | Description |
|
|
152
|
+
|---|---|
|
|
153
|
+
| **Hybrid Retrieval** | 6-channel: vector + BM25 + L0/L1/L2 multi-vector + KG graph (PPR) |
|
|
154
|
+
| **4 Retrieval Profiles** | default, writing, debug, fact-check — tuned for different tasks |
|
|
155
|
+
| **Session Continuity** | `checkpoint_session` + `resume_context` (full/light/summary modes) with repo-state guard |
|
|
156
|
+
| **Session Distiller** | 3-layer conversation compression: microcompact → LLM summary → knowledge extraction |
|
|
157
|
+
| **Conversation Import** | Import from Claude Code, Claude.ai, ChatGPT, Slack, and plaintext |
|
|
158
|
+
| **Topic Tags** | Intra-scope topic partitioning — auto-detected, filterable in search |
|
|
159
|
+
|
|
160
|
+
### Memory Lifecycle & Governance
|
|
161
|
+
|
|
162
|
+
| Capability | Description |
|
|
163
|
+
|---|---|
|
|
164
|
+
| **Memory Evolution** | Supersede chains, decay scoring, LLM importance, consolidation, archival |
|
|
165
|
+
| **Smart Promotion** | Evidence → durable memory with conflict guards, merge resolution, and audit trail |
|
|
166
|
+
| **Privacy Tiers** | 4-tier (`ephemeral` / `private` / `durable` / `shared`) with cascade forgetting |
|
|
167
|
+
| **Admission Control** | Write-time gating: noise filter, importance floor, dedup, rate limiting |
|
|
168
|
+
| **Memory Lint** | Contradiction, duplicate, stale, and orphan detection with health score |
|
|
169
|
+
| **Offline Consolidation** | `dream` command: clustering, merging, pruning of accumulated memories |
|
|
170
|
+
|
|
171
|
+
### Reasoning & Structure
|
|
172
|
+
|
|
173
|
+
| Capability | Description |
|
|
174
|
+
|---|---|
|
|
175
|
+
| **Knowledge Graph** | Entity relation graph with PPR algorithm for multi-hop questions |
|
|
176
|
+
| **Constructive Retrieval** | Multi-source candidate expansion + grounded context reconstruction |
|
|
177
|
+
| **Narrative Architecture** | 3-layer autobiographical metadata (life-period → general-event → specific-event) |
|
|
178
|
+
| **Skill Memory** | Store, retrieve, and promote executable skills from recurring patterns |
|
|
179
|
+
| **Predictive Reminders** | Behavioral-signal prediction engine surfaces "you might need this" suggestions |
|
|
180
|
+
| **6 Categories** | profile, preferences, entities, events, cases, patterns — with category-aware merge strategies |
|
|
181
|
+
|
|
182
|
+
### Visibility & Operations
|
|
183
|
+
|
|
184
|
+
| Capability | Description |
|
|
185
|
+
|---|---|
|
|
186
|
+
| **Dashboard** | Web UI with stats, category distribution, growth trends, and health |
|
|
187
|
+
| **Workflow Observation** | Dedicated append-only workflow health records, outside regular memory |
|
|
188
|
+
| **Structured Assets** | Pins, briefs, and distilled summaries — not just raw logs |
|
|
189
|
+
| **Data Checkup** | Data quality health checks on the memory store |
|
|
190
|
+
| **Export Graph** | Export interactive HTML knowledge graph visualization |
|
|
191
|
+
| **Batch Operations** | Store up to 20 memories in a single call with dedup |
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## New in v2.1: Philosophy-Informed Memory
|
|
196
|
+
|
|
197
|
+
v2.0 built the operational memory platform; v2.1 added philosophy-informed memory behavior.
|
|
198
|
+
|
|
199
|
+
Five upgrades derived from 9 research dimensions in philosophy of memory, each mapped to concrete engineering:
|
|
200
|
+
|
|
201
|
+
- **Emotion-Aware Decay** *(Affective Memory Theory)* — Memories with strong emotional content decay 20-30% slower. Keyword-based emotion detection computes `salience` (mnemonic significance), which feeds into the Weibull half-life formula and a rebalanced 4-factor evolution score. Zero LLM cost.
|
|
202
|
+
|
|
203
|
+
- **Memory Ethics Layer** *(Right to Be Forgotten / GDPR Art. 17)* — Four privacy tiers (`ephemeral` / `private` / `durable` / `shared`). Cascade forgetting engine that propagates deletion through KG triples, evolution chains, pin assets, and briefs. Full audit trail. `forget_memory` MCP tool for agent-driven deletion.
|
|
204
|
+
|
|
205
|
+
- **Autobiographical Narrative** *(Narrative Identity Theory / Conway's 3-layer model)* — Memories are tagged with `lifePeriod → generalEvent → specificEvent` hierarchy, orthogonal to existing 6 categories. Retrieval pulls narrative siblings. Context rendering groups by life period. Rule-based tagger with EN+CN support.
|
|
206
|
+
|
|
207
|
+
- **Constructive Retrieval** *(Simulation Theory / Michaelian)* — Instead of returning raw stored text, RecallNest now reconstructs context from an expanded candidate set: KG neighbors + evolution chains + cluster members + narrative siblings. Source-map grounded coverage replaces lexical overlap. Contradictions are detected and flagged.
|
|
208
|
+
|
|
209
|
+
- **Predictive Prospective Memory** *(Mental Time Travel / Tulving)* — Heuristic prediction engine that surfaces "you might need this" reminders from behavioral signals: stale checkpoint open loops, corrected workflow observations, high-frequency dormant memories, and uncovered query topics. Zero LLM cost. Auto-expire in 7 days if unaccepted.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## New in v2.2: Retrieval Quality Hardening
|
|
214
|
+
|
|
215
|
+
v2.1 added philosophy-informed behavior; v2.2 closes the last three engine-layer gaps identified by a frontier research scan (ACC, PI-LLM, TSM).
|
|
216
|
+
|
|
217
|
+
- **Memory Confidence Meta-tags** *(ACC / Dual-Process UQ)* — Each memory now carries structured `ConfidenceMetadata` (score, reliability tier: `direct` / `inferred` / `hearsay`). Auto-assigned from source on write (`manual` = 0.9, `agent` = 0.7, `conversation_import` = 0.5). Retrieval scores are weighted by confidence. `resume_context` tags low-confidence items with `[低置信]`.
|
|
218
|
+
|
|
219
|
+
- **Interference Detection + Active Forgetting Gate** *(PI-LLM / SleepGate)* — Semantic cluster detection identifies groups of near-duplicate memories competing for retrieval. Enhanced RIF keeps only top-K (default 3) per cluster; extras are demoted 50% instead of removed. Write-time pre-warning: when a scope accumulates ≥5 high-similarity active memories, the weakest is flagged `pending_review`. `data_checkup` reports interference density.
|
|
220
|
+
|
|
221
|
+
- **Temporal Validity Windows** *(TSM / TiMem / Zep)* — `store_memory` accepts `validUntil` (expiration) and `eventTime` (when the event actually happened). `search_memory` supports `validAt` (point-in-time query) and `includeExpired` (demote 80% instead of hide). Auto-GC applies 2× decay acceleration to expired memories.
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
143
225
|
## Architecture
|
|
144
226
|
|
|
145
227
|
```
|
|
@@ -157,7 +239,7 @@ bun run src/cli.ts doctor
|
|
|
157
239
|
│ Integration Layer │
|
|
158
240
|
│ ┌─────────────────────┐ ┌────────────────────────────┐ │
|
|
159
241
|
│ │ MCP Server │ │ HTTP API Server │ │
|
|
160
|
-
│ │
|
|
242
|
+
│ │ 41 tools │ │ 21 endpoints │ │
|
|
161
243
|
│ └─────────┬───────────┘ └──────────┬─────────────────┘ │
|
|
162
244
|
└────────────┼─────────────────────────┼───────────────────┘
|
|
163
245
|
└──────────┬──────────────┘
|
|
@@ -187,11 +269,19 @@ bun run src/cli.ts doctor
|
|
|
187
269
|
└──────────────────────────────────────────────────────────┘
|
|
188
270
|
```
|
|
189
271
|
|
|
272
|
+
### Internal Design
|
|
273
|
+
|
|
274
|
+
- **L0 / L1 / L2 Dynamic Folding** — every memory stores 3 granularity layers (one-liner / bullet summary / full content); retrieval dynamically selects which layer to return based on relevance score and token budget
|
|
275
|
+
- **Weibull Decay + Emotion Modulation** — memories decay along a parametric Weibull curve; importance scores modulate the half-life, and emotional salience extends it further (up to 30%)
|
|
276
|
+
- **Vector Pre-filter + LLM Dedup** — 90% of dedup decisions use cheap cosine similarity (>= 0.92); only borderline cases invoke LLM judgment, keeping costs low without sacrificing accuracy
|
|
277
|
+
- **Category-Aware Merge Strategies** — `profile` and `preferences` use merge-on-conflict (latest wins); `events` and `cases` use append-only (history preserved)
|
|
278
|
+
- **Display Score vs Elimination Score** — dual-track retrieval: tier floor prevents core memories from ever dropping out, while decay boost lets fresh memories surface temporarily without permanently displacing stable ones
|
|
279
|
+
|
|
190
280
|
> Full architecture deep-dive: [`docs/architecture.md`](docs/architecture.md)
|
|
191
281
|
|
|
192
282
|
---
|
|
193
283
|
|
|
194
|
-
##
|
|
284
|
+
## Interfaces
|
|
195
285
|
|
|
196
286
|
RecallNest serves two interfaces:
|
|
197
287
|
|
|
@@ -210,77 +300,8 @@ Examples live in [`integrations/examples/`](integrations/examples/):
|
|
|
210
300
|
|
|
211
301
|
---
|
|
212
302
|
|
|
213
|
-
## Core Features
|
|
214
|
-
|
|
215
|
-
### Hybrid Retrieval
|
|
216
|
-
|
|
217
|
-
```
|
|
218
|
-
Query → Embedding ──┐
|
|
219
|
-
├── Hybrid Fusion → Rerank → Weibull Decay → Filter → Top-K
|
|
220
|
-
Query → BM25 FTS ──┘
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
- **Vector search** — semantic similarity via LanceDB ANN
|
|
224
|
-
- **BM25 full-text search** — exact keyword matching via LanceDB FTS
|
|
225
|
-
- **Hybrid fusion** — vector + BM25 combined scoring
|
|
226
|
-
- **Reranking** — Jina cross-encoder reranking
|
|
227
|
-
- **Decay + tiering** — Weibull freshness model with Core / Working / Peripheral tiers
|
|
228
|
-
|
|
229
|
-
### Session Continuity
|
|
230
|
-
|
|
231
|
-
The killer feature for multi-window workflows:
|
|
232
|
-
|
|
233
|
-
- **`checkpoint_session`** — snapshot current work state (decisions, open loops, next actions)
|
|
234
|
-
- **Repo-state guard** — saved checkpoints strip `git status` / modified-file text so volatile repo state does not contaminate later handoffs
|
|
235
|
-
- **`resume_context`** — compose startup context from checkpoints + durable memory + pins
|
|
236
|
-
- **Managed rules** — integration scripts install continuity rules so `resume_context` fires automatically
|
|
237
|
-
|
|
238
|
-
### Workflow Observation
|
|
239
|
-
|
|
240
|
-
RecallNest now keeps workflow observations in a dedicated append-only store instead of stuffing them into the regular memory index:
|
|
241
|
-
|
|
242
|
-
- **`workflow_observe`** — record whether `resume_context`, `checkpoint_session`, or another workflow primitive succeeded, failed, was corrected, or was missed
|
|
243
|
-
- **`workflow_health`** — aggregate 7d / 30d health for one workflow or show a degraded-workflow dashboard
|
|
244
|
-
- **`workflow_evidence`** — package recent issue observations, top signals, and suggested next actions for debugging
|
|
245
|
-
|
|
246
|
-
These records live under `data/workflow-observations`, not in the 6 memory categories, and they are never composed into `resume_context` as stable recall.
|
|
247
|
-
Managed MCP / HTTP continuity calls now append observations automatically for `resume_context` and `checkpoint_session`, while repo-state sanitization is recorded as a `corrected` checkpoint observation instead of polluting durable memory.
|
|
248
|
-
|
|
249
|
-
### Memory Promotion & Conflict Resolution
|
|
250
|
-
|
|
251
|
-
Raw transcripts don't silently become long-term memory:
|
|
252
|
-
|
|
253
|
-
- **Evidence → durable** — explicit `promote_memory` with `canonicalKey` and provenance
|
|
254
|
-
- **Conflict guards** — canonical-key collisions surface as conflict candidates
|
|
255
|
-
- **Resolution** — keep existing, accept new, or merge — with advice and cluster views
|
|
256
|
-
- **Audit + escalation** — `conflicts audit --export` for operational review
|
|
257
|
-
|
|
258
|
-
### Retrieval Profiles
|
|
259
|
-
|
|
260
|
-
| Profile | Best for | Bias |
|
|
261
|
-
|---------|----------|------|
|
|
262
|
-
| `default` | Everyday recall | Balanced |
|
|
263
|
-
| `writing` | Drafting and idea mining | Broader semantic, older material OK |
|
|
264
|
-
| `debug` | Errors, commands, fixes | Keyword-heavy, recency-biased |
|
|
265
|
-
| `fact-check` | Evidence lookup | Tighter cutoff, exact-match bias |
|
|
266
|
-
|
|
267
|
-
### Memory Categories
|
|
268
|
-
|
|
269
|
-
| Category | Description | Strategy |
|
|
270
|
-
|----------|-------------|----------|
|
|
271
|
-
| `profile` | User identity and background | Merge |
|
|
272
|
-
| `preferences` | Habits, style, dislikes | Merge |
|
|
273
|
-
| `entities` | Projects, tools, people | Merge |
|
|
274
|
-
| `events` | Things that happened | Append |
|
|
275
|
-
| `cases` | Problem → solution pairs | Append |
|
|
276
|
-
| `patterns` | Reusable workflows | Merge |
|
|
277
|
-
|
|
278
|
-
Details: [`docs/memory-categories.md`](docs/memory-categories.md)
|
|
279
|
-
|
|
280
|
-
---
|
|
281
|
-
|
|
282
303
|
<details>
|
|
283
|
-
<summary><strong>MCP Tools (
|
|
304
|
+
<summary><strong>MCP Tools (41 tools)</strong></summary>
|
|
284
305
|
|
|
285
306
|
| Tool | Description |
|
|
286
307
|
|------|-------------|
|
|
@@ -313,11 +334,23 @@ Details: [`docs/memory-categories.md`](docs/memory-categories.md)
|
|
|
313
334
|
| `auto_capture` | Heuristically extract and store memory signals from text (zero LLM calls) |
|
|
314
335
|
| `set_reminder` | Set a prospective memory reminder to surface in a future session |
|
|
315
336
|
| `consolidate_memories` | Cluster near-duplicate memories and merge them (dry-run by default) |
|
|
337
|
+
| `store_skill` | Store an executable skill with trigger conditions and verification |
|
|
338
|
+
| `retrieve_skill` | Retrieve matching executable skills by semantic similarity |
|
|
339
|
+
| `scan_skill_promotions` | Scan cases/patterns for promotion candidates to skills |
|
|
340
|
+
| `list_tools` | Discover available tools by tier (core/advanced/full) |
|
|
341
|
+
| `batch_store` | Store up to 20 memories in a single call with dedup |
|
|
342
|
+
| `distill_session` | Distill a conversation into structured knowledge via 3-layer pipeline |
|
|
343
|
+
| `import_conversations` | Import conversations from Claude Code, ChatGPT, Slack, and more |
|
|
344
|
+
| `data_checkup` | Run data quality health checks on the memory store |
|
|
345
|
+
| `dream` | Run offline memory consolidation (clustering, merging, pruning) |
|
|
346
|
+
| `memory_lint` | Run memory quality checks: contradictions, duplicates, stale entries, orphans |
|
|
347
|
+
| `forget_memory` | Cascade-delete a memory with KG cleanup, pin archival, and audit trail |
|
|
348
|
+
| `export_graph` | Export memories as an interactive HTML knowledge graph |
|
|
316
349
|
|
|
317
350
|
</details>
|
|
318
351
|
|
|
319
352
|
<details>
|
|
320
|
-
<summary><strong>HTTP API (
|
|
353
|
+
<summary><strong>HTTP API (21 endpoints)</strong></summary>
|
|
321
354
|
|
|
322
355
|
Base URL: `http://localhost:4318`
|
|
323
356
|
|
|
@@ -341,6 +374,7 @@ Base URL: `http://localhost:4318`
|
|
|
341
374
|
| `/v1/resume` | POST | Compose startup context for a fresh window |
|
|
342
375
|
| `/v1/search` | POST | Advanced search with full metadata |
|
|
343
376
|
| `/v1/stats` | GET | Memory statistics |
|
|
377
|
+
| `/v1/lint` | GET | Memory quality lint report |
|
|
344
378
|
| `/v1/health` | GET | Health check |
|
|
345
379
|
|
|
346
380
|
Full documentation: [`docs/api-reference.md`](docs/api-reference.md)
|
|
@@ -374,6 +408,12 @@ bun run src/cli.ts conflicts resolve af70545a --keep-existing
|
|
|
374
408
|
bun run src/cli.ts conflicts resolve af70545a --merge
|
|
375
409
|
bun run src/cli.ts conflicts resolve --all --keep-existing --status open
|
|
376
410
|
|
|
411
|
+
# Memory health & visualization
|
|
412
|
+
bun run src/cli.ts lint # memory quality report
|
|
413
|
+
bun run src/cli.ts lint --scope project:myapp # lint a specific scope
|
|
414
|
+
bun run src/cli.ts graph --open # export & open knowledge graph
|
|
415
|
+
bun run src/cli.ts graph --max-nodes 50 # smaller graph
|
|
416
|
+
|
|
377
417
|
# Ingestion & diagnostics
|
|
378
418
|
bun run src/cli.ts ingest --source all
|
|
379
419
|
bun run src/cli.ts doctor
|
|
@@ -381,17 +421,36 @@ bun run src/cli.ts doctor
|
|
|
381
421
|
|
|
382
422
|
</details>
|
|
383
423
|
|
|
384
|
-
|
|
385
|
-
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## Multilingual Support
|
|
427
|
+
|
|
428
|
+
RecallNest works out of the box with English. For multilingual memory (Chinese, Japanese, Thai, and 20+ more), install [babel-memory](https://github.com/AliceLJY/babel-memory) with the language packs you need:
|
|
386
429
|
|
|
387
430
|
```bash
|
|
388
|
-
|
|
389
|
-
|
|
431
|
+
# Chinese
|
|
432
|
+
npm install babel-memory jieba-wasm
|
|
433
|
+
|
|
434
|
+
# Japanese
|
|
435
|
+
npm install babel-memory @sglkc/kuromoji
|
|
436
|
+
|
|
437
|
+
# Thai
|
|
438
|
+
npm install babel-memory wordcut
|
|
439
|
+
|
|
440
|
+
# European languages (German, French, Spanish, Russian, etc.)
|
|
441
|
+
npm install babel-memory snowball-stemmers
|
|
442
|
+
|
|
443
|
+
# Multiple languages at once
|
|
444
|
+
npm install babel-memory jieba-wasm @sglkc/kuromoji snowball-stemmers
|
|
390
445
|
```
|
|
391
446
|
|
|
392
|
-
|
|
447
|
+
RecallNest auto-detects babel-memory at startup — no configuration needed. Without babel-memory, RecallNest still works perfectly with standard BM25 text search.
|
|
393
448
|
|
|
394
|
-
|
|
449
|
+
---
|
|
450
|
+
|
|
451
|
+
## Project Status & Roadmap
|
|
452
|
+
|
|
453
|
+
RecallNest is actively maintained. All major architecture phases are complete — see the full [Roadmap](ROADMAP.md) for current priorities and future plans.
|
|
395
454
|
|
|
396
455
|
---
|
|
397
456
|
|
|
@@ -406,21 +465,34 @@ RecallNest started as a fork of [memory-lancedb-pro](https://github.com/CortexRe
|
|
|
406
465
|
|
|
407
466
|
| Source | Contribution |
|
|
408
467
|
|--------|-------------|
|
|
409
|
-
| [
|
|
468
|
+
| [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) by [@win4r](https://github.com/win4r) | Fork base — hybrid retrieval, decay modeling, and memory architecture |
|
|
410
469
|
| Claude Code | Foundation and early project scaffolding |
|
|
411
470
|
| OpenAI Codex | Productization and MCP expansion |
|
|
412
471
|
|
|
413
472
|
Special thanks to Qin Chao ([@win4r](https://github.com/win4r)) and the [CortexReach](https://github.com/CortexReach) team for the foundational work.
|
|
414
473
|
|
|
415
|
-
|
|
474
|
+
<details>
|
|
475
|
+
<summary><strong>Ecosystem</strong></summary>
|
|
476
|
+
|
|
477
|
+
Part of the **小试AI** open-source AI workflow:
|
|
478
|
+
|
|
479
|
+
| Project | Description |
|
|
480
|
+
|---------|-------------|
|
|
481
|
+
| [babel-memory](https://github.com/AliceLJY/babel-memory) | Multilingual preprocessing for BM25 — 27+ languages, zero deps |
|
|
482
|
+
| [content-alchemy](https://github.com/AliceLJY/content-alchemy) | 5-stage AI writing pipeline |
|
|
483
|
+
| [content-publisher](https://github.com/AliceLJY/content-publisher) | Image generation + layout + WeChat publishing |
|
|
484
|
+
| [wechat-ai-bridge](https://github.com/AliceLJY/wechat-ai-bridge) | Run Claude Code / Codex / Gemini in WeChat with session management |
|
|
485
|
+
| [telegram-ai-bridge](https://github.com/AliceLJY/telegram-ai-bridge) | Telegram bots for Claude, Codex, and Gemini |
|
|
486
|
+
| [telegram-cli-bridge](https://github.com/AliceLJY/telegram-cli-bridge) | Telegram CLI bridge for Gemini CLI |
|
|
487
|
+
| [openclaw-tunnel](https://github.com/AliceLJY/openclaw-tunnel) | Docker ↔ host CLI bridge (/cc /codex /gemini) |
|
|
488
|
+
| [openclaw-config](https://github.com/AliceLJY/openclaw-config) | OpenClaw bots configuration and memory backup |
|
|
489
|
+
| [digital-clone-skill](https://github.com/AliceLJY/digital-clone-skill) | Build digital clones from corpus data |
|
|
490
|
+
| [claude-code-studio](https://github.com/AliceLJY/claude-code-studio) | Multi-session collaboration platform for Claude Code |
|
|
491
|
+
| [cc-genius](https://github.com/AliceLJY/cc-genius) | Web-based Claude chat client (PWA) — self-hosted, iPad-ready |
|
|
492
|
+
| [agent-nexus](https://github.com/AliceLJY/agent-nexus) | One-command installer for memory + remote control |
|
|
493
|
+
| [cc-cabin](https://github.com/AliceLJY/cc-cabin) | Complete Claude Code workflow scaffold |
|
|
416
494
|
|
|
417
|
-
|
|
418
|
-
<picture>
|
|
419
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=AliceLJY/recallnest&type=Date&theme=dark&transparent=true" />
|
|
420
|
-
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=AliceLJY/recallnest&type=Date&transparent=true" />
|
|
421
|
-
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=AliceLJY/recallnest&type=Date&transparent=true" />
|
|
422
|
-
</picture>
|
|
423
|
-
</a>
|
|
495
|
+
</details>
|
|
424
496
|
|
|
425
497
|
## License
|
|
426
498
|
|