Hindsight 开源 AI 记忆系统贡献指南：从克隆仓库到提交第一份 PR

Hindsight 开源 AI 记忆系统贡献指南从克隆仓库到提交第一份 PR【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个开源的 AI 代理记忆系统Agent Memory负责让 AI 代理记住、回忆并整合信息。本文是它的贡献指南覆盖本地开发环境搭建、提交第一份 PR、协作规则和发布流程。参与开发 Hindsight你能接触生产级的 Python / TypeScript / Rust 混合工程并在真实的 Agent Memory 场景中积累系统开发经验。快速跑通 Hindsight 本地开发环境这一节解决clone 之后如何十分钟跑起来的问题。做完三件事本地就具备完整的开发环境。Hindsight 是 monorepo服务端 API 在 hindsight-api-slim/前端控制面板在 hindsight-control-plane/Python / TypeScript / Rust 三套 SDK 在 hindsight-clients/文档在 hindsight-docs/。先拿到代码git clone https://gitcode.com/GitHub_Trending/hindsight2/hindsight cd hindsight然后运行一键初始化脚本./scripts/dev/setup.sh源码见 scripts/dev/setup.sh。它会自动补齐缺失的工具链uv/Python、Node/npm、Rust/cargo、从.env.example生成.env、配置 git 钩子、安装全部 Python 与 Node 工作区依赖并预下载本地 ML 模型和分词器让 API 可以离线运行。脚本可重复执行每个步骤都会检查是否已完成并自动跳过--skip-build只装依赖、--skip-models跳过模型下载、--with-docs顺带构建文档站、--force强制重建产物。脚本跑完后只留一步人工操作编辑.env把你的 LLM API 密钥和配置填进去。接下来启动服务三个脚本各管一块./scripts/dev/start-api.sh # 本地 API 服务 ./scripts/dev/start-control-plane.sh # Web 控制面板 ./scripts/dev/start-docs.sh # 文档站Hindsight 贡献指南本地开发环境中的控制面板 Knowledge 页面Hindsight AI 记忆系统控制面板的本地运行效果左侧为记忆图谱视图想确认本地开发环境是否真正就绪就跑到测试这一步cd hindsight-api uv run pytest tests/Hindsight 记忆库开发环境中的知识页树与页面详情控制面板树形视图由记忆自动合成的知识页提交你的第一个贡献这一节解决改完代码怎么交付的问题分支怎么开、提交前要跑什么、PR 里写什么。分支规范从main拉出功能分支命名形如feature/your-feature-name保持改动范围小、一个分支只做一件事。测试要求提 PR 前在hindsight-api/目录下跑完完整测试套件并确认全部通过。PR 描述要素改了什么、解决了哪个问题或新增了什么功能、测试结果如何、相关 issue 编号。涉及 API 行为的改动同步更新hindsight-docs/下的相关页面。风格底线Python 代码带类型注解、跟随仓库既有模式、函数保持单一职责——这一点在下一节的规则清单里再展开。协作红线与工具链这一节用一张规则清单交代协作中的硬性约定哪些检查是自动执行的、issue 报告需要包含什么。自动化 git 钩子git commit 前自动执行的检查脚本仓库内置的钩子位于 .githooks/用./scripts/setup-hooks.sh挂载setup.sh已完成这步。钩子触发时并行执行 scripts/hooks/lint.sh语言自动执行的检查Pythonruff check --fix、ruff format、ty checkTypeScripteslint --fix、prettier检查项由钩子驱动通常无需手动执行需要单独跑时用./scripts/hooks/lint.sh复现完整流程或在对应包目录单独执行uv run ruff check --fix .、uv run ruff format .、uv run ty check hindsight_api。代码风格跟随现有代码模式不引入新的风格变体。issue 报告四要素清晰的问题描述、可复现的步骤、预期行为与实际行为的对比、环境信息操作系统、Python 版本。四者齐全维护者定位问题的速度会明显更快。进阶方向发布、架构与客户端生成这一节面向有前几次提交经验、想往深处走的贡献者。发布流程由 scripts/release.sh 自动化例如./scripts/release.sh 0.5.0。脚本依次完成更新全部组件的版本号、重新生成 OpenAPI 规范与 Python / TypeScript / Rust 三套客户端 SDK、更新文档版本号、创建发布提交与 git tag、推送到远端触发 CI/CD 发包。两条容易踩的坑先记下再动手开发期在__init__.py里改版本号不需要重新生成客户端客户端只在正式发布时重新生成。不要手动运行./scripts/generate-clients.sh除非你正在验证生成逻辑本身的变更。架构级改动集中在 hindsight-api-slim/hindsight_api/engine/涉及数据库结构变化时需要按 alembic 迁移目录 的模式新增迁移并跑迁移相关测试。多语言 SDK 位于hindsight-clients/下的python/、typescript/、rust/一般不建议手改——它们由 API 规范生成。性能与基准评测和回归在 hindsight-dev/benchmarks/ 下进行改动检索或记忆整合链路时先跑一遍基准再提 PR。BEAM 10M 基准Hindsight 相对行业基线的得分对比从 issue 列表挑一个带新手标签的任务跑通本地环境后按上面的流程交付你的第一份 PR 即可。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考