项目定位与设计目标

GoodMemory 是一个本地优先（local-first）的记忆层（memory layer），专门为 AI 产品与编程代理（coding agents）提供持久化的上下文存储与检索能力。其核心设计目标是让 AI 助手（包括 Claude Code、Codex、Cursor、Cline 等）在多次会话之间保持长期记忆，从而避免每次重启都需要重新加载历史信息。

该项目以独立服务的形式运行，同时通过 Model Context Protocol（MCP）与多种主流 AI 编辑器或代理集成。这意味着 GoodMemory 既可以作为开发者的本地工具，也可以作为团队共享的记忆后端。 资料来源：README.md:1-40

技术栈与运行时

GoodMemory 的核心实现采用 TypeScript + Bun 构建，提供了高性能的 HTTP API 桥接层。Bun 作为运行时替代了传统的 Node.js，从而获得了更快的启动速度和更优的 I/O 性能。项目的根目录 package.json 定义了统一的工作区配置，支持 monorepo 结构下的多个子包。

graph LR
    A[AI 客户端<br/>Claude Code / Cursor / Cline] -->|MCP 协议| B[GoodMemory 服务]
    B --> C[本地存储<br/>SQLite / 文件系统]
    B --> D[HTTP API<br/>认证桥接]
    D --> E[Python SDK]
    D --> F[TypeScript SDK]

除了核心服务，仓库还提供：

• 官方 Python 客户端：通过 clients/python/pyproject.toml 进行打包，遵循标准的 PEP 621 规范，可通过 pip install 直接安装
• Inspector Web 应用：位于 apps/inspector-web/，是一个基于浏览器的前端检查器，用于可视化浏览和调试记忆内容
• Docker 镜像支持：Dockerfile 提供了容器化部署方案，便于在远程服务器或 CI 环境中运行 资料来源：package.json:1-30、Dockerfile:1-20、clients/python/pyproject.toml:1-25

核心功能与集成生态

GoodMemory 的功能可以从三个维度来理解：

1. 一键式客户端集成

通过 goodmemory setup 命令，可以自动配置 Codex 与 Claude Code 的环境变量与 MCP 端点，无需手动编辑配置文件。这降低了开发者的接入门槛。

2. 独立 MCP 服务模式

作为标准的 MCP server 运行，兼容以下客户端：

• Cursor、Windsurf、Cline、Claude Desktop
• Gemini CLI、OpenCode
• 任何遵循 MCP 协议的客户端

3. 多语言 SDK 访问

通过经认证的 HTTP 桥接层，外部程序可以使用 TypeScript 或 Python SDK 直接读写记忆数据。这使得 GoodMemory 不仅服务于编辑器，也能被自动化脚本或后端服务消费。 资料来源：clients/python/README.md:1-40、README.md:30-60

部署形态与社区演进

GoodMemory 支持多种部署形态：

在版本演进方面，社区重点关注的是稳定性与跨平台兼容性。从 v0.5.1 到 v0.7.0 的更新中，开发团队持续完善了对更多 MCP 客户端的支持，并优化了认证桥接层的可靠性。由于该项目强调"本地优先"，因此数据主权和离线可用性也是用户社区反复讨论的热点话题。 资料来源：README.md:50-80、apps/inspector-web/package.json:1-20

典型使用场景

• 代码助手记忆：让 Claude Code 记住项目特定的命名规范、架构决策与历史 Bug 修复方案
• 跨会话知识沉淀：在多次开发会话之间保留设计文档的要点与用户偏好
• 团队记忆共享：通过部署中心化的 GoodMemory 实例，使团队成员能够查询共享的项目记忆
• AI 代理上下文增强：为长时运行的编码代理（如 OpenCode）提供持久的工作上下文

整体而言，GoodMemory 定位为一个轻量级、可嵌入、可扩展的记忆中间件，填补了当前 AI 编程工具链中"长期上下文持久化"的空白。 资料来源：README.md:1-40、clients/python/README.md:1-30

模块定位与职责

apps/inspector-web/src 是 GoodMemory 项目中检视器（Inspector）前端应用的源代码根目录，承担"本地优先记忆层"的可视化与人机交互职责。它面向使用 Codex、Claude Code、Cursor、Windsurf、Cline、Claude Desktop、Gemini CLI、OpenCode 等客户端的开发者与终端用户，让他们能够通过浏览器查看、检索、修改和删除 AI 代理长期记忆条目。模块本身不直接持久化数据，而是作为经过认证的 HTTP 桥接（authenticated HTTP bridge）的图形壳层，所有数据访问都委托给由 TypeScript/Bun 编写的后端 API 与官方 Python 客户端共用的同一份数据契约 资料来源：apps/inspector-web/src/api.ts。

启动与渲染管线

应用入口由 main.tsx 负责：它定位 DOM 根节点、注入 styles.css 全局样式表，并挂载顶层 <App /> 组件 资料来源：apps/inspector-web/src/main.tsx。App.tsx 作为容器组件，承担两项工作：一是组合各 UI 子组件形成侧边栏、记忆列表、详情面板与搜索框的整体布局；二是维护当前会话、过滤条件与认证状态的本地状态机，并将来自 api.ts 的响应投影到这些组件上 资料来源：apps/inspector-web/src/App.tsx。styles.css 在此层级提供深色与浅色主题切换、栅格布局、列表与详情视图的间距与排版，确保本地优先设计在浏览器中保持一致性 资料来源：apps/inspector-web/src/styles.css。

数据访问与认证层

api.ts 封装了与后端 HTTP 桥接的全部调用，包括记忆条目列表查询、按关键词检索、单条详情读取、新增与删除等操作。它对请求路径、超时与错误码进行了统一处理，避免业务组件重复编写 fetch 样板代码 资料来源：apps/inspector-web/src/api.ts。auth.ts 与之配套，负责在浏览器端持久化 Bearer Token 或会话凭证，并在每次 API 调用前注入 Authorization 头，从而满足 v0.5.1 起引入的"经认证的 HTTP 桥接"安全约束 资料来源：apps/inspector-web/src/auth.ts。

UI 组件与交互防护

components/ConfirmDialog.tsx 是复用度最高的弹窗组件，专门为不可逆操作（删除记忆、清空会话、批量重置）提供二次确认。它阻断误触，并将用户的最终决定回传给上层业务组件 资料来源：apps/inspector-web/src/components/ConfirmDialog.tsx。模块内其它组件按职责拆分：列表组件负责分页与滚动加载，详情组件负责渲染 Markdown 与元数据，搜索组件负责防抖输入与高亮匹配，所有组件共享 styles.css 的设计令牌。

模块协作示意

flowchart TD
    A[main.tsx<br/>挂载根节点] --> B[App.tsx<br/>布局与状态]
    B --> C[api.ts<br/>HTTP 桥接]
    B --> D[auth.ts<br/>Token 持久化]
    C --> E[(GoodMemory 后端 API)]
    D --> C
    B --> F[components/ConfirmDialog.tsx<br/>二次确认]
    B --> G[styles.css<br/>主题与栅格]

社区与版本背景

依据社区证据，GoodMemory 在 v0.5.1 引入对 Codex 与 Claude Code 的一键 goodmemory setup，并以独立 MCP 形态支持 Cursor、Windsurf、Cline、Claude Desktop、Gemini CLI、OpenCode 等多端客户端；apps/inspector-web/src 模块作为这些客户端之外的可视化补充，使本地记忆数据具备可审计、可清理的能力。最新版本 v0.7.0 在保持本地优先特性的同时，强化了 HTTP 桥接的认证与跨端协作，因此本模块中 auth.ts 与 api.ts 的边界尤为重要 资料来源：apps/inspector-web/src/auth.ts:1-1 资料来源：apps/inspector-web/src/api.ts:1-1。

概述与定位

src/api/ 是 GoodMemory v0.5.1 暴露给上层应用、AI 智能体（Codex、Claude Code、Cursor 等）以及外部客户端的 TypeScript/Bun 公共接口层。该模块既承担"门面（facade）"职责，也把"能力描述（capability descriptor）"、"事件摄取（event ingestion）"、"评估支持（evaluation support）"与"演化运行时（evolution runtime）"等子系统按职责切分。社区中提到的 "TypeScript/Bun API, authenticated HTTP bridge, and official Python client" 即由该层作为契约来源。资料来源：src/api/createGoodMemory.ts:1-40、src/api/contracts.ts:1-30。

入口与对象工厂

createGoodMemory 是整个 API 模块的主要装配点，负责把内部子系统组合成一个可被消费的实例：

• 接受配置对象（包含存储路径、桥接地址、认证令牌等），返回一个聚合对象。
• 内部依赖注入 evolutionRuntime、agentEventIngestion、evalSupport，并把 capabilityDescriptor 的声明作为只读元信息向外暴露。
• 通过 contracts.ts 中定义的强类型契约（输入参数、返回结构、错误码），保证调用方在 TypeScript 与 Python 客户端侧均获得一致语义。

典型调用方式（伪代码）：const gm = await createGoodMemory({ store: '~/.goodmemory', bridge: 'http://localhost:7443' })。

资料来源：src/api/createGoodMemory.ts:20-80、src/api/contracts.ts:1-60。

能力描述与契约

capabilityDescriptor.ts 与 contracts.ts 共同构成 API 的"自我描述"与"类型契约"层：

• Capability Descriptor：以机器可读形式声明当前实例支持哪些操作（例如 memory.upsert、memory.search、evolution.run、eval.score），用于 MCP、Cursor、Windsurf 等客户端自动发现能力。
• Contracts：使用 TypeScript 类型与运行时校验（schema）双重保障，定义事件结构、记忆条目 schema、演化策略参数等，避免上层在跨语言调用时出现字段漂移。

资料来源：src/api/capabilityDescriptor.ts:1-50、src/api/contracts.ts:30-120。

事件摄取、评估与演化运行时

API 模块的三个运行时子系统分别处理不同的写/读/演化场景：

社区讨论中提到的 "Dura..." 持久化与本机优先特性，主要由 agentEventIngestion 写入路径与 evolutionRuntime 的本地调度共同保证。

资料来源：src/api/agentEventIngestion.ts:1-70、src/api/evolutionRuntime.ts:1-90、src/api/evalSupport.ts:1-60。

架构关系图

flowchart TB
    Client[AI 客户端 / MCP / Python SDK] -->|HTTP / IPC| Bridge[HTTP Bridge]
    Bridge --> Facade[createGoodMemory]
    Facade --> Cap[capabilityDescriptor]
    Facade --> Ingest[agentEventIngestion]
    Facade --> Evo[evolutionRuntime]
    Facade --> Eval[evalSupport]
    Ingest --> Store[(本地记忆存储)]
    Evo --> Store
    Contracts[contracts.ts] -.类型契约.-> Facade

与外部生态的衔接

• Codex / Claude Code：通过 goodmemory setup 完成 first-party 配置后，CLI 直接调用本模块入口。
• MCP 客户端（Cursor、Windsurf、Cline、Claude Desktop、Gemini CLI、OpenCode）：读取 capabilityDescriptor 自注册工具，无需手写胶水代码。
• Python 客户端：借助 contracts.ts 导出的 JSON Schema 在运行时反序列化，确保与 TypeScript 实现字段一致。

资料来源：src/api/createGoodMemory.ts:60-120、src/api/capabilityDescriptor.ts:30-80。

使用建议与注意事项

• 优先通过 createGoodMemory 工厂获取实例，避免直接 new 内部类，以便后续版本（当前最新为 v0.7.0）进行内部重构。
• 自定义事件 schema 时，应同时更新 contracts.ts 中的类型与 agentEventIngestion 的校验逻辑，否则摄取阶段会拒绝写入。
• 演化策略属于长任务，建议在调用 evolutionRuntime 时传入进度回调，避免阻塞调用方 UI。
• 评估流水线在 CI 中应使用 evalSupport 提供的离线模式，以避免对在线桥接的依赖。

Runtime 模块是 GoodMemory 的本地优先（local-first）内存执行层，负责在客户端进程内协调上下文组装、记忆读写以及会话溢出（spillover）控制。它向上游为 MCP 客户端、CLI 工具以及 HTTP Bridge 提供统一的 API 入口，向下层与持久化存储和索引模块交互，确保 AI 代理在受限上下文窗口内仍能稳定访问长期记忆。资料来源：src/runtime/index.ts:1-40

1. 模块定位与职责划分

Runtime 模块位于 src/runtime 目录，整体职责可归纳为三点：

1. 上下文装配：根据当前会话、用户与代理标识，从存储中检索相关记忆条目并组装成注入提示。资料来源：src/runtime/contextService.ts:1-60
2. 公共 API 暴露：通过 public.ts 收敛所有对外可见的方法，避免内部实现细节泄漏到上层。资料来源：src/runtime/public.ts:1-45
3. 溢出与回退策略：当组装结果超过预设阈值时，触发 spillover.ts 中的降级或截断逻辑。资料来源：src/runtime/spillover.ts:1-55

下表展示了三个核心文件在调用链中的位置关系：

2. 上下文服务（Context Service）

contextService.ts 是 Runtime 模块的核心协调者。它接收来自 CLI、MCP 或 HTTP Bridge 的请求，依据会话标识（session id）、代理类型（agent type）与时间窗口参数，查询持久化层并返回排序后的记忆片段。该服务在内存中维护一份轻量级缓存，用于减少重复检索的开销，同时通过 types.ts 中定义的接口保证类型一致性。资料来源：src/runtime/contextService.ts:60-130、src/runtime/types.ts:1-50

关键行为包括：

• 按相关性（relevance）与新鲜度（recency）对记忆进行排序；
• 支持增量上下文，仅返回自上次调用以来的新增条目；
• 在检索失败时返回空上下文而非抛出异常，以保证上游调用方的稳定性。

3. 公共 API（Public Surface）

public.ts 文件充当 Runtime 模块的稳定门面（facade）。所有面向用户的接口——例如记忆写入、上下文读取、设置初始化——都必须经过该文件导出，避免内部模块被直接依赖。这种封装使得 Runtime 能够在不影响调用方的前提下重构内部实现。资料来源：src/runtime/public.ts:45-120

公共 API 设计的两个原则：

• 最小化导出：仅暴露使用文档中明确描述的功能；
• 幂等保证：同一调用重复执行不会产生副作用或重复写入。

4. 溢出策略（Spillover）

当上下文装配结果超过目标模型的窗口预算时，spillover.ts 介入处理。其策略通常包括截断低相关条目、按段落压缩，以及在极端情况下回退到最近一次成功快照。该机制确保即使在长会话中，注入提示仍能保持在可用范围内。资料来源：src/runtime/spillover.ts:55-140

flowchart LR
    A[客户端请求] --> B[public.ts]
    B --> C[contextService.ts]
    C --> D{超出阈值?}
    D -- 否 --> E[返回上下文]
    D -- 是 --> F[spillover.ts]
    F --> E
    E --> G[持久化层]

5. 与最新版本（v0.7.0）的关联

社区资料显示，GoodMemory v0.7.0 在延续 v0.5.1 的本地优先特性的同时，强化了对 Codex、Claude Code、Cursor、Windsurf 等客户端的适配。Runtime 模块作为这些适配层的统一执行底座，其上下文服务与溢出策略直接影响到代理在多客户端环境下的稳定性与一致性表现。资料来源：v0.5.1 发布说明

6. 小结

Runtime 模块通过 contextService、public、spillover 三个子文件，构建了一个高内聚、低耦合的本地执行层。它既保证了记忆访问的性能与稳定性，也为上层适配层提供了清晰的契约边界，是 GoodMemory 实现“local-first 内存层”定位的关键组件。资料来源：src/runtime/index.ts:40-80

Pitfall Log / 踩坑日志

项目：hjqcan/GoodMemory

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/hjqcan/GoodMemory | host_targets=mcp_host, claude_code, claude, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/hjqcan/GoodMemory | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/hjqcan/GoodMemory | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/hjqcan/GoodMemory | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/hjqcan/GoodMemory | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/hjqcan/GoodMemory | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/hjqcan/GoodMemory | release_recency=unknown