gingugu Skill 技能

技能简介

Gingugu 是一个本地优先的 MCP 服务器，为 AI 编码助手补上缺失的「长期大脑」——跨会话、跨仓库、跨项目持久保存的结构化记忆。你的 AI 每天早上都从零开始：上周修过的 bug、一个月前定下的架构，全部蒸发。Gingugu 不是把观察扔进平铺抽屉的杂物盒，而是按命名空间、类型与关系组织，按相关性、新鲜度与置信度排序，在你开始工作时自动唤起上下文的结构化记忆系统。它完全本地运行：单个 SQLite 文件，无云端、无 API Key、无遥测。更重要的是，它把「记忆纪律」也装进了盒子——一键安装的钩子协议强制代理在正确时机读写记忆，而不是指望模型自觉。Python 3.11+，MIT 协议，1370 个测试通过。

核心能力

• 结构化长期记忆：跨会话、跨仓库、跨项目保存，按命名空间、类型（事实/偏好/决策/任务等）与关系组织，支持置信度标注。
• 四因子综合排序：相关性 × 新鲜度 × 访问频次 × 置信度合成打分，自动把「此刻最该想起的」排在最前。
• 混合检索：BM25（SQLite FTS5）加本地向量（fastembed 或 Ollama 后端），以倒数排名融合（RRF）合并，实测 MRR 0.828、recall@5 0.983，无需部署向量数据库。
• 内置记忆纪律协议：gingugu init 一条命令安装 SessionStart 钩子，在每次会话开头注入记忆协议（先查记忆再提问、观察当下即保存、关系只记检索推不出的），Stop 钩子检查有实质工作的会话确实落了盘。
• 主动安全机制：非自愿回忆（提示词唤醒的相关记忆自动浮现）、绊线（记忆标记「不可错过」的工具调用在执行前拦截）、热小兵（给子代理分发围栏内预载好的独立记忆）。
• 知识整合与界面：按需合并重复与相关知识；附带 Memory Explorer UI，可视化知识图谱与仪表盘。
• 21 个 MCP 工具：程序化可编程，含记忆读写、检索、关系、整合等完整接口，与各 MCP 客户端通用。

安装配置

1. 环境要求：Python 3.11+，本地运行，无需云端账号或 API Key。
2. 安装：通过 pip 或 uv 安装 gingugu 包，随后在目标仓库执行 gingugu init 完成接线。
3. 接入 MCP 客户端：在 Claude Code、Cursor 等客户端的 MCP 配置中添加 gingugu 服务器条目。
4. 检索后端配置：默认 fastembed（ONNX，首次下载约 80MB 模型，之后完全离线）；设置 MEMORY_EMBEDDINGS_BACKEND=ollama 可复用已在运行的 Ollama；MEMORY_EMBEDDINGS_ENABLED=false 可关闭语义检索只用 BM25。

使用步骤

1. 安装并初始化：安装包后在仓库运行 gingugu init，SessionStart 钩子即随每次会话自动注入记忆协议。
2. 正常干活：代理按协议在观察当下保存记忆，会话结束 Stop 钩子校验落盘，你无需粘贴任何规则文件。
3. 主动查询：直接向代理提问，或用 21 个 MCP 工具按命名空间、类型、关系检索记忆。
4. 唤起与拦截：开始新工作时非自愿回忆自动浮现相关上下文；危险操作被绊线在执行前拦截。
5. 维护整理：用整合功能合并重复知识，打开 Memory Explorer UI 查看知识图谱与健康仪表盘。

适用场景

• 跨会话延续：昨天的决策、上周的修复、上月的架构约定，今天开工自动在场。
• 多工具切换：上午 Claude Code、下午 Cursor，记忆跟着人走而不是锁在单个工具里。
• 多仓库多项目：按命名空间隔离又相互关联，团队与个人的知识各归其位。
• 防止重复犯错：绊线机制让记忆里标记过的坑在工具调用执行前被拦下。
• 子代理隔离协作：热小兵给每个子代理分发预载的围栏记忆，互不污染。

适用人群

日常使用 Claude Code、Cursor 等 AI 编码助手、苦恼于「每次都要重新解释背景」的开发者；并行多个项目、需要跨仓库沉淀架构决策的工程师；在意数据主权、拒绝记忆上云的隐私敏感用户；研究 Agent 记忆机制的技术团队。

工作原理

所有记忆、FTS5 索引与向量都存在单个 SQLite 文件中。写入时按命名空间与类型结构化落盘，可触发去重与整合；检索时 BM25 关键词与本地向量双路召回，RRF 融合后按四因子合成打分排序。纪律层由钩子保证：SessionStart 注入协议文本到会话开头，Stop 校验写入，绊线在工具调用前对照记忆规则，全部由宿主钩子强制执行，不依赖模型自觉。语义检索可整体关闭，退化为纯 BM25，依然完全本地。

官方链接

• GitHub 仓库：https://github.com/gingugu/gingugu
• PyPI 主页：https://pypi.org/project/gingugu/