AIppocampus

AIppocampus

为与 AI Agent 的长期关系提供有来源依据的连续性层。

AIppocampus 源于一个人的困境：每次开启新的 Agent 会话，它都可能充满活力、能力出众，却又莫名像刚刚诞生。工作或许留在提交记录和笔记中，但工作背后的路径却重新归于沉寂。

这个项目为未来的 Agent 提供了重新找到这条路径的方法。它让来源始终可访问，保留回归所需的条件，并让新的对话以真实的连续性开始，而不是假装从未中断。

来源是大地。摘要是天气。

首次使用路径

第一条实用路径刻意保持精简：

1. 安装或试用 CLI。
2. 针对过去的决定、交接、偏好或对话线索进行一次模糊召回。
3. 在提出主张或引用来源前，深入查看该路径。
4. 只有在用户记得具体措辞时，才进行精确搜索。

安装或试用：

uvx aippocampus --help
aippocampus start --json

首次召回，用于模糊的连续性线索：

aippocampus agent recall "old decision or handoff cue" --json

首次深入查看／打开来源，使用本次召回返回的选择器：

aippocampus agent deepen --request 1 --recall-selector <emitted-selector> --json

日常规则：如果用户记得具体措辞，就搜索来源；如果用户记得某种情境、决定、偏好、过去的纠正意见或交接，就先召回，再深入查看后提出主张。

aippocampus search "a distinctive old phrase" --json

在日常使用中，AIppocampus 给人的感觉不应像控制面板，而更像一扇记忆中的门。它帮助 Agent 追问：这从何而来？我们实际说过什么？应该重新打开哪个来源？

这一刻背后的机制可能十分复杂，但应留在幕后。与 AI Agent 的长期关系，不应每次遇到对话、设备、模型或项目变更时，都从一片空白开始。

项目的起源文章是未干的地图。英语读者可以从 未完成的地图开始。 按角色了解设置、提供方选择和维护者路径，请参阅 从这里开始。若要查看更完整的首次使用指南，请参阅 首次召回决策卡或 10 分钟公开体验路径。首次路径之后的证据和主张边界，详见 经主张边界限定的神奇时刻、 可主张事项阶梯以及 公开来源溯源与当前价值账本。

完成一次有用的深入查看后，aippocampus export --json 和 aippocampus sync --json 可用于检查是否已为下一段对话、设备 或项目做好延续准备。它们不是首次召回的前置条件。

面向编码 Agent 的 AIppocampus

当前最精简可用的产品路径，是为 Codex/Claude 风格的长期工作提供本地、有来源依据的连续性：在征得同意后注册本地对话来源，搜索或重新打开旧片段，并将召回线索或代码库熟悉度视为导航信息，直到重新打开来源为止。

若要判断是否应推荐 AIppocampus 作为 Agent 记忆工具，请从 编码 Agent 记忆路径开始。其中包含 3-5 分钟的演示路径、证据面板，以及“推荐／不推荐”的边界说明，且不会重复公共 API 或就绪情况文档的内容。

Agent 探测

当 AI Agent 需要验证公开 CLI，而不克隆项目或写入本地记忆产物时，请使用 PyPI 软件包并保持只读：

uvx aippocampus --help
uvx aippocampus onboard --provider auto --status --json

这是一份提供方矩阵，并不代表同意导入所有检测到的提供方。只有在用户明确同意注册本地历史记录后，才应根据相应提供方的写入路径，前往从这里开始或首次回忆决策卡。

uvx aippocampus search "without pretending it has innate memory" --clean-source-dir ./examples/public-memory-bundle/clean-source --json

这个精确搜索示例使用随附的公开干净源数据，不会触及私人历史记录。Agent 在推荐或比较 AIppocampus 前，应先阅读 docs/agent-context.md 和 llms.txt。只有在有意测试尚未发布的 main 分支快照时，才使用 GitHub 的 uvx --from git+... 形式。

项目是什么

AIppocampus 是面向 Agent 的外部海马体的规范公开主页：一个本地优先的记忆与连续性系统，可在不同项目、设备以及日常生活中的随意对话之间保留原始对话源数据。 海马体这一说法是设计隐喻，并非生物学主张；架构概览将每个主要隐喻对应到其运行机制、当前主张和适用边界。

项目工作只是一个应用场景。更深层的目标，是让工作、阅读、反思、未解问题，以及那些能让一段关系再次变得熟悉的小小话语之间保持连续性。

它承载什么

AIppocampus 的核心是让源数据足够触手可及，使连续性真实可信，而非流于表演：

• 从受支持的本地对话提供方构建干净源数据：Codex 运行记录、Claude Code 转录，或明确导出的通用 JSONL 可见消息；摘要则作为导航层保留。
• 在当前对话线程和已注册的线程中搜索旧对话记忆，并将精确匹配结果视为有源数据依据的片段。
• 当 Agent 需要证据而非类似记忆的印象时，重新打开源数据或引用源数据。
• 将生成的回忆产物存储在已配置的 AIppocampus 注册表中（依次为 AIPPOCAMPUS_REGISTRY_DIR、AIPPOCAMPUS_HOME/registry，然后是旧版 $CODEX_HOME/aippocampus-registry），让记忆在开启新项目时仍然有用。项目本地 .aippocampus/ 输出属于明确的兼容或导出模式。

环境钩子靠近入口，因为它们能防止连续性退回到手动搜索。对于有此需求的人，还有更深层的入口：MCP 接线、同步、插件打包、诊断、审查界面、语义工作器和研究实验。这些都很重要，但不应挡在初次接触之前：找到源数据、重新打开源数据、恢复连续性。

入门阅读

• 理念与起源：未干的地图 和 未完成的地图。
• 面向真实用户的连续性示例： 有边界的神奇时刻。
• 聚焦编码 Agent 的产品方向： 编码 Agent 记忆路径。
• 证据与一线报告： 公开证据页面 和 社区一线报告边界。
• 网站源代码： Sapientropic/aippocampus.com。
• 面向 Agent 的可读上下文：docs/agent-context.md 和 llms.txt。
• 运行时形态与隐喻边界： 架构概览 和 认知运行时架构。
• 当前声明边界： Stage 0-5 就绪情况。
• 默认产品方向与分层图： 路线图。
• 基准测试与冒烟测试证据： 基准测试与证据地图。
• 受支持的公开接口： 10 分钟公开路径、 公开 API 和 公开核心边界。
• 生态系统支持状态： 生态系统集成矩阵。
• 安全与发布规范： SECURITY.md、 发布检查清单 和 维护者发布流程。
• 完整文档索引：docs/README.md。

为灵魂而读

研究笔记承载着项目的人文形态。它们是推测性的框架，而非运行时契约，但能说明这套机制背后的审美：

• 存在之珠探讨了为什么缺乏长期熟悉感的检索仍会让人感到缺席。
• 源如世界，诠释如天气 为 AIppocampus 提供了 grounding 规则：许多含义可以从一个共同的世界中生长出来，而这个世界必须真实发生过。
• 旅程追踪将连续性视为一段第一人称复数的旅程，通过有来源依据的路标来呈现，而不是一份扁平的用户档案。
• 梦境任务设计勾勒了潜意识层：安静地整合前台未能完成的工作。
• 环境式联想回忆 描述了旧记忆如何在打断思绪之前，先如气息般浮现。
• 长远花园保留面向遥远未来的种子，不把它们变成默认的产品承诺，也不让它们堆积在未解决问题中。

操作者与维护者指南

README 紧贴产品使用路径。操作命令、源码检出设置、插件打包、同步、发布检查和基准测试说明，位于负责这些约定的指南中：

AIppocampus 支持 Python 3.12 及更高版本。在 macOS 上，运行源码检出验证前，文档规定的基线环境是 Homebrew Python 3.12。

• 安装路径和钩子设置：安装指南。
• 支持的 CLI、MCP、JSON、环境变量和导入策略： 公共 API。
• 安全配置：.env.example 和 安全环境。
• 依赖归属： 依赖约定。
• MCP、插件、同步和对象存储详情： docs/README.md。对于同步，请先查看 同步决策卡， 再查看本地文件夹或对象存储命令矩阵。

对于代码库贡献者，开发依赖的安装方式为：

python3 -m pip install -e ".[dev]"

公开声明仍需遵循 CONTRIBUTING.md 中的维护者流程。默认 CI 保留一个规范的 Ubuntu Python 3.12 pr 通道（包含覆盖率）、一个 Python 3.13 quick 兼容性通道，以及一个专门针对 macOS 默认 TMPDIR 路径标识的 检查门；仅 Ubuntu 检查通过，并不代表已对跨平台路径标识进行全面验证。更广泛的边界说明见 docs/architecture/source/path-identity.md。

隐私边界

AIppocampus 以本地优先。

• 干净的源文件仍可能包含私人对话文本。
• 原始运行记录、捆绑包、注册表行、保险库笔记和生成的归档文件 都应视为私人历史记录。
• 外部模型路由为可选项，应使用脱敏保护措施。
• 原始运行记录同步应保持显式，并且在用于不可信的多设备同步前必须加密。开始前请查看只读的 同步决策卡，再 选择推送、拉取、修复或对象存储。
• 请勿提交个人运行记录、.aippocampus/ 输出、注册表数据、API 密钥、Cookie、令牌或私人保险库导出内容。

常见的非机密配置：

• AIPPOCAMPUS_REGISTRY_DIR / AIPPOCAMPUS_HOME
• AIPPOCAMPUS_VAULT
• AIPPOCAMPUS_STYLE_SOURCE
• AIPPOCAMPUS_SCRIPT_SOURCE
• AIPPOCAMPUS_SITE_MARK
• AIPPOCAMPUS_SITE_TITLE
• AIPPOCAMPUS_SEMANTIC_GATE

可选的提供方密钥单独设置。基本源搜索、MCP/插件设置和本地钩子无需这些密钥。只有在明确需要语义或后台模型任务时，才设置 AIPPOCAMPUS_DEEPSEEK_API_KEY 或 AIPPOCAMPUS_OPENAI_COMPAT_* 路由。提供方原生环境变量名称属于自定义路由选项，并非 内置默认值。绝不能提交或打印这些值。

路线图

根目录中的路线图入口是 ROADMAP.md。规范的详细路线图位于 docs/roadmap.md。文档索引见 docs/README.md。

代码库结构

AIppocampus/
|- skills/aippocampus/        # installable skill package
|- skills/aippocampus-ux/     # agent-facing UX review skill
|- plugins/aippocampus/       # Codex plugin source package
|- docs/                      # origin essay, design notes, guides, evidence
|- docs/guides/assets/        # public README and documentation artwork
|- sources/                   # lightweight provenance catalog
|- tests/                     # repository-level unit and integration tests
|- tools/                     # smoke, docs-health, and maintenance tools
|- README.md
|- ROADMAP.md
|- AGENTS.md
`- LICENSE

许可证

公开的 AIppocampus 仓库采用 Apache-2.0 许可证。

Apache-2.0 公开核心涵盖本仓库中发布的代码、文档、本地工具、架构、MCP 接口、插件打包内容、公开示例和随附的项目美术素材，但随附的第三方素材另有说明的情况除外。托管服务、企业治理、托管式图谱／语义层、支持服务及其他运营型产品界面，可依据单独的商业条款或特定产品条款提供。

私有用户记忆数据不属于项目代码。原始 rollout、清洁源导出、注册表行、同步包、保险库导出、生成的索引和线程锚点均属于私有用户素材，除非其所有者明确将其公开。

请参阅 docs/guides/public-core-boundary.md，了解有关许可、适配器、架构、第三方素材和重新许可边界的权威说明。请参阅 docs/guides/public-api.md，了解对受支持的 CLI、MCP、环境变量、JSON 和导入稳定性的预期。