nan-forget

NaN Forget

面向 AI 编码工具的长期记忆。

会话结束后，你的 AI 会忘记一切。NaN Forget 可以解决这个问题。

---

安装（3 个步骤）

npx nan-forget setup

就这么简单。向导会安装 Ollama、嵌入模型、Claude hooks、MCP 配置，以及供 Codex 风格 Agent 使用的项目 AGENTS.md。重启 Claude Code 或重新打开 Codex。你的 AI 现在会记住信息。

无需 API 密钥。无需 Docker。完全本地运行。永久免费。

---

工作原理

flowchart LR
    A["You talk to your AI tool"] --> B["It learns things"]
    B --> C["nan-forget saves to SQLite"]
    C --> D["Session ends"]
    D --> E["New session starts"]
    E --> F["nan-forget loads context"]
    F --> G["Your AI remembers"]

1. 正常工作。 你的 Agent 会在工作过程中将决策、偏好和事实保存到本地 SQLite 记忆数据库。
2. 会话结束。 记忆会保存在 ~/.nan-forget/memories.db 中。较旧的记忆会自动整合为长期条目。
3. 开始新会话。 nan-forget 会加载过往会话中的上下文。你今天在项目 B 工作时，3 个月前在项目 A 中做出的身份验证决策也会浮现出来。

---

自动处理记忆

你无需手动调用保存或搜索。以下是后台的处理流程：

Claude Code（完全自动）

事件	触发操作	处理方式
会话开始	memory_sync	轻量级握手——检查健康状态、加载统计信息并列出项目。不会执行繁重的搜索。
你发送消息	UserPromptSubmit hook	nan-forget recall 会自动搜索相关记忆，并将相关上下文注入对话。
你讨论某个主题	memory_search	每当可能存在相关上下文时，Claude 都会动态搜索数据库——就像你按需回忆信息一样。
Claude 学到新信息	memory_save	Claude 会立即保存决策、偏好和事实。工具说明会告诉 Claude“你必须调用此工具”。
Claude 编写 .md 文件	PostToolUse hook	memory-sync.js 会拦截写入、解析 frontmatter，并通过 nan-forget add 自动将内容保存到 SQLite。
会话结束	SessionEnd hook	session-end.js 会扫描对话记录，找出尚未保存的决策和事实，并将最重要的 5 项保存到数据库。
每保存 10 次或每隔 24h	自动整合	较旧的记忆会被聚类并整合为长期条目。原始记忆会被归档。

四层保护机制确保不会丢失任何内容：

1. 每条消息都自动回忆（UserPromptSubmit hook）
2. Claude 主动保存（指令式工具说明）
3. Hook 捕获 .md 写入（PostToolUse 拦截）
4. 会话结束时全面检查（SessionEnd 对话记录扫描）

Codex、Cursor 和其他工具

Codex 和类似的 Agent 可以很好地配合 nan-forget 使用，但它们通常需要通过指令文件或 shell/API 回退方案来实现，而不是使用 Claude 的 hook 模式：

1. 运行设置命令：npx nan-forget setup
2. 在仓库中使用生成的 AGENTS.md。它会指示 Codex 风格的 Agent 自动执行 sync、search、save 和 checkpoint。
3. 在对话期间使用 REST 或 CLI 回退方案。Agent 可以调用 localhost:3456 上的 REST API，或使用 nan-forget sync、nan-forget search、nan-forget add 和 nan-forget checkpoint 等本地命令。

REST API 和 CLI 现在已能充分支持重要的记忆工作流，因此 Claude 保存的记忆可以从 Codex 中搜索，反之亦然。

# Start the REST API
nan-forget api

# The system prompt tells your agent exactly what endpoints to call
nan-forget prompt

---

斜杠命令

在 Claude Code 中输入以下命令：

命令	功能
/nan-forget	加载过往会话中的上下文
/nan-forget stats	显示记忆健康状态
/nan-forget clean	运行垃圾回收
/nan-forget compact	强制整合记忆
/nan-forget health	检查服务是否正在运行
/nan-forget start	启动所有服务

---

适用于任何大模型

Claude 使用 MCP。Codex 可以使用 AGENTS.md，并搭配 CLI/REST 回退方案：

# Start the API
nan-forget api

# Get the system prompt for your agent
nan-forget prompt

Codex、Cursor 和 Claude 共用同一个记忆数据库。

curl http://localhost:3456/memories/search?q=auth
curl -X POST http://localhost:3456/memories/sync -d '{"project":"my-app"}'
curl -X POST http://localhost:3456/memories/checkpoint \
  -H 'content-type: application/json' \
  -d '{"task_summary":"Fixed auth regression","problem":"Expired tokens were not refreshed","solution":"Added refresh handling in middleware","files":["src/auth.ts"],"concepts":["auth","jwt"],"project":"my-app"}'

---

快速入门（CLI）

nan-forget add "We use FastAPI, not Django. Railway deploys faster."
nan-forget add --type decision "Auth is Clerk, not custom JWT"
nan-forget search "what auth system"
nan-forget stats

---

架构（专家部分）

以下内容面向希望了解 nan-forget 底层工作原理的开发者。

---

问题

大模型在不同会话之间没有记忆。每次对话都从零开始。你得重新解释自己的技术栈，Claude 会推翻上个月做出的决定，会话结束后上下文也会消失。

现有解决方案（Mem0）面向的是将记忆嵌入产品的应用开发者。我们面向的是你——每天使用 AI 工具、希望 AI 能记住信息的开发者。

设计：受大脑启发的双层记忆

flowchart TB
    subgraph Short["Short-Term Memory"]
        MD[".md files<br/>Current session context<br/>Disposable scratch paper"]
    end
    subgraph Long["Long-Term Memory"]
        DB["SQLite + sqlite-vec<br/>~/.nan-forget/memories.db<br/>Semantic search + decay"]
    end
    subgraph Auto["Automatic Processes"]
        Hook["Hooks (3)<br/>PostToolUse: .md → DB<br/>UserPromptSubmit: auto-recall<br/>SessionEnd: transcript sweep"]
        Consolidate["Consolidation Engine<br/>Clusters + summarizes aging memories"]
        GC["Garbage Collection<br/>Decay, dedup, expiry"]
    end
    MD -->|"hook intercepts"| Hook
    Hook -->|"nan-forget add"| DB
    DB --> Consolidate
    Consolidate --> DB
    DB --> GC

短期记忆 = Claude 内置的 .md 文件。可丢弃。仅用于当前会话。

长期记忆 = 使用 sqlite-vec 进行向量搜索的 SQLite 数据库。单个文件。永久保存。可在所有会话、所有项目和所有大模型工具之间搜索。

三个钩子可自动处理记忆：

• PostToolUse 拦截 .md 文件写入，并将其保存到数据库。
• UserPromptSubmit 会在每条用户消息上运行 nan-forget recall，自动搜索相关上下文记忆。
• SessionEnd 会扫描对话记录，查找尚未保存的决定并保存其中最重要的 5 条。

三阶段检索流程

记忆搜索遵循与人类回忆相同的路径：

flowchart LR
    Q["Query"] --> S1["Stage 1: Recognition<br/>Fast vector match<br/>Returns summaries only"]
    S1 --> S2["Stage 2: Recall<br/>Full content fetch<br/>Cross-project expansion"]
    S2 --> S3["Stage 3: Association<br/>Spreading activation<br/>Related memories surface"]
    S3 --> R["Results ranked by<br/>similarity x decay x frequency x confidence"]

阶段	执行内容	开销
识别（模糊）	预取 50 条候选项，返回排名前 5 的摘要。开销低。	1 次向量搜索
回忆（清晰）	获取完整内容。跨项目扩大搜索范围（不筛选项目）。	N 次单点查找
联想	基于质心，在 sqlite-vec 中搜索相关记忆。根据正向 ID 进行扩散激活。	1 次向量搜索

评分公式：

final_score = vector_similarity * decay_weight * frequency_boost * confidence_boost
decay_weight = (0.5 ^ (days / 30)) ^ (1 - confidence)
frequency_boost = log2(access_count + 1) / 10 + 1
confidence_boost = 0.5 + 0.5 * confidence

高置信度记忆（经过辩论验证、经人工批准）衰减速度慢得多，排名也更高。置信度为 0.85 的核心记忆，衰减速度约为正常速率的 15%——除非被新信息取代，否则实际上会永久保留。跨项目搜索意味着你在处理项目 B 时，项目 A 中有关身份验证的决定也会显示出来。

整合引擎

老化的记忆不会直接删除，而是会压缩整合为长期条目：

flowchart TB
    A["10+ aging memories<br/>about the same topic"] --> B["Cluster by project + type<br/>+ vector similarity > 0.8"]
    B --> C{"OpenAI key<br/>available?"}
    C -->|"Yes"| D["LLM summarizes cluster<br/>into 1-2 sentences"]
    C -->|"No"| E["Deterministic merge<br/>concatenate + deduplicate"]
    D --> F["Save consolidated entry<br/>with fresh vector embedding"]
    E --> F
    F --> G["Archive originals<br/>with backlink"]

每保存 10 条记忆或每隔 24 小时后，都会自动触发。无需用户操作。

13 个 MCP 工具

工具	用途
memory_sync	轻量级会话握手：健康检查 + 统计信息 + 项目列表
memory_save	保存一条记忆（由 Claude 主动自动调用）
memory_search	使用三阶段检索进行语义搜索（深度 1–3）
memory_get	按 ID 获取特定记忆
memory_update	更改内容、类型或标签
memory_archive	软删除（从搜索结果中隐藏，但不会真正删除）
memory_consolidate	强制整合老化的记忆
memory_clean	垃圾回收（衰减、去重、过期处理、同步 MEMORY.md）
memory_stats	记忆健康状况面板
memory_health	检查 Ollama、REST API 是否正在运行
memory_start	启动 Ollama + REST API
memory_checkpoint	完成任务后，保存完整的问题→解决方案上下文
memory_compress	将持久化的 .md 记忆文件压缩为最简占位文件

结构化记忆

memory_save 接受结构化字段，以生成更丰富的向量表示：

字段	类型	用途
content	string	完整描述（必填）
type	string	fact、decision、preference、task、context
project	string	项目名称
problem	string	面临的挑战
solution	string	解决方法
concepts	string[]	可搜索的标签（["auth", "jwt", "middleware"]）
files	string[]	涉及的文件（["src/auth.ts"]）
confidence	number	信任度 0.0–1.0（默认值根据来源确定）
provenance	string	save、checkpoint、debate、human
tier	string	regular 或 core（根据来源自动确定）

所有字段会一同嵌入为单个向量。搜索“JWT auth bug”时，即使记忆内容并未逐字包含这些词，也能找到带有相关概念标签的记忆。

记忆层级

并非所有记忆都同等重要。经过辩论验证和人工批准的记忆属于核心记忆——它们衰减得更慢，在搜索结果中的排名更高，也能更久地保留在垃圾回收中。

来源	默认置信度	自动层级	衰减速率
save	0.5	regular	正常（30 天半衰期）
checkpoint	0.65	regular	慢约 35%
debate	0.85	core	慢约 85%
human	0.95	core	慢约 95%

核心记忆是为即将推出的 nan-debate 系统设计的——经人工批准验证的多 AI 辩论结果会作为高可信知识持久保存，几乎不会随时间淡化。

检查点工作流

完成任务后，调用 memory_checkpoint，并提供 task_summary、problem、solution、files、concepts 和 project。这会将完整的问题→解决方案上下文保存到长期记忆中。每完成一项任务，就创建一个检查点。

记忆压缩

memory_compress 会扫描 .claude/projects/*/memory/，查找已持久化到数据库的 .md 文件。已持久化的文件会被替换为最简存根，从而减少上下文窗口膨胀。

REST API（面向非 MCP 大模型）

与 MCP 服务共用同一个 SQLite 数据库——Claude 保存的记忆可从 Codex 中搜索，反之亦然。

POST   /memories              — Save a memory (supports problem/solution/files/concepts)
POST   /memories/checkpoint   — Save completed-task context
POST   /memories/sync         — Lightweight session handshake
GET    /memories/search?q=... — Semantic search
GET    /memories/:id          — Get by ID
PATCH  /memories/:id          — Update
DELETE /memories/:id          — Archive
POST   /memories/consolidate  — Compact aging memories
POST   /memories/clean        — Garbage collection
GET    /memories/stats        — Memory health
GET    /memories/instructions — System prompt for LLMs

获取任意大模型的系统提示词：

nan-forget prompt
# or
curl http://localhost:3456/memories/instructions

嵌入

提供方	模型	维度	费用
Ollama（默认）	nomic-embed-text	768	免费，本地运行
OpenAI	text-embedding-3-small	1536	使用你的 API 密钥

自动检测：Ollama 正在运行？使用它。未运行？检查是否设置了 OPENAI_API_KEY。无需配置。

数据存储

所有数据都存储在单个 SQLite 文件 ~/.nan-forget/memories.db 中。无需 Docker 或服务，更新也不会导致数据丢失。

• 向量搜索：sqlite-vec 扩展（余弦距离，在进程内嵌入运行）
• 元数据：标准 SQL 表，并在 user_id、status、project、type 上建立索引
• 备份：复制一个文件。恢复：放回该文件。
• 导出：nan-forget export 将所有记忆导出为 JSON。

记忆生命周期

flowchart TB
    A["New memory saved"] --> B["Active in SQLite<br/>Searchable, scored"]
    B --> C{"Accessed<br/>recently?"}
    C -->|"Yes"| D["Score stays high<br/>frequency_boost increases"]
    C -->|"No"| E["Decay weight drops<br/>0.5^(days/30)"]
    E --> F{"Decay < 0.3?"}
    F -->|"Yes"| G["Consolidation candidate<br/>Clustered + summarized"]
    F -->|"No"| B
    G --> H["New consolidated entry<br/>Originals archived"]
    D --> B
    E --> I{"Decay < 0.1?"}
    I -->|"Yes"| J["Archived by GC"]
    I -->|"No"| F

垃圾回收（零大模型成本）

所有清理工作都是确定性的。不调用 API，不进行大模型推理。

• 衰减 GC：归档衰减权重低于 0.1 的记忆（普通记忆约 100 天，核心记忆约 600 天以上）
• 过期处理：归档已超过 expires_at 日期的记忆
• 干扰解决：对相似度 >0.95 的匹配项去重，保留访问次数较多的一项
• MEMORY.md 同步：使用每个项目评分最高的前 5 条记忆刷新工作记忆

核心记忆（置信度 ≥ 0.85）比普通记忆更能长久地经受垃圾回收，因为其衰减公式会降低时间因子的影响：decay^(1 - confidence)。一条置信度为 0.85、存续 200 天的记忆，其衰减权重仍高于 0.1。

设计理念

NaN Forget 围绕三个原则构建：轻量、自动和本地。

轻量

无需 Docker、云服务或占用 RAM 的后台进程。整个存储层只是一个 SQLite 文件（约 3 MB）。嵌入通过你很可能已经安装的 Ollama 运行。记忆操作（保存、搜索、去重、垃圾回收）完全不调用大模型——全部以确定性方式完成。

自动

四个钩子会在会话的各个阶段捕获上下文——你无需手动调用保存：

1. UserPromptSubmit 会在你发送每条消息时搜索记忆
2. 工具描述会指示 Claude 在决策和事实出现时保存它们
3. PostToolUse 会拦截 .md 文件写入并将其持久化
4. SessionEnd 会扫描对话记录，找出任何遗漏内容

老化的记忆会自动整合。重复项会合并。未使用的记忆会以 30 天半衰期衰减。无需维护。

本地

你的数据保留在本机的 ~/.nan-forget/memories.db 中。无需账号或 API 密钥（Ollama 免费且在本地运行），也不收集遥测数据。备份只需复制一个文件。适用于 Claude Code（MCP）、Codex/Cursor（REST API）和终端（CLI）——共用同一个数据库和记忆。

与其他记忆工具的区别

大多数 AI 记忆解决方案（Mem0、claude-mem）是为将记忆嵌入产品的应用开发者设计的，或者需要 Docker／云服务才能运行。NaN Forget 专为你而设计——适用于每天使用 AI 工具、希望上下文能跨会话保留且无需管理基础设施的开发者。

主要设计差异：

• 检索：采用三阶段流程（识别 → 回忆 → 扩散激活），并按衰减加权评分，而非简单的向量搜索
• 结构：记忆包含 problem、solution、concepts 和 files 字段——即使搜索关键词不匹配，也能找到相关上下文
• 成本：记忆操作（保存、搜索、去重、整合、GC）都以确定性方式完成——不调用大模型，也不产生 API 费用
• 设置：只需一条命令（npx nan-forget setup），无需 Docker、容器，也无需管理服务

源码结构

src/
  sqlite.ts         SQLite + sqlite-vec storage layer (schema, CRUD, vector search)
  embeddings.ts     OpenAI / Ollama abstraction
  writer.ts         Memory writer with dedup (>0.92 = merge)
  retriever.ts      Three-stage retrieval pipeline
  consolidator.ts   LLM summarization + deterministic fallback
  cleaner.ts        GC: decay, expiry, dedup, MEMORY.md sync
  services.ts       Service management (Ollama, REST API)
  memory-md.ts      MEMORY.md manager
  types.ts          Shared types (Memory, MemoryType, etc.)
  mcp/server.ts     MCP server, 13 tools
  api/server.ts     REST API server
  cli/index.ts      CLI commands + hook helpers
  setup/index.ts    Setup wizard (Ollama, hooks, MCP config)

.claude/
  commands/nan-forget.md   Slash command for manual control
  hooks/memory-sync.js     PostToolUse hook (auto-saves .md → SQLite)
  hooks/session-end.js     SessionEnd hook (transcript sweep for unsaved memories)
  settings.json            Hook config (PostToolUse + SessionEnd + UserPromptSubmit)

---

由 NaN Logic LLC 构建

• NaN Mesh — AI Agent 的信任网络
• NaN Forget — 适用于任何大模型的长期记忆

MIT 许可证。