长记忆使用Hooks对接Claude Code-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

概述

Claude Code Hooks是Claude Code提供的会话生命周期钩子机制。当您在Claude Code中进行特定操作（如启动会话、上下文压缩、退出会话、调用工具）时，Claude Code会自动执行您预先注册的脚本，实现在会话关键节点插入自定义逻辑。

每个Hook通过stdin接收Claude Code传入的JSON输入（包含会话ID、工作目录、工具名称等信息），通过stdout返回JSON输出来影响Claude Code的行为（如注入上下文、阻止危险操作）。

AnalyticDB for PostgreSQL长记忆服务可以基于这一机制构建的自动记忆管理方案——在Claude Code的生命周期触发点上完成记忆的加载、保存和守护，用户和Claude均无需手动操作。

工作原理

AnalyticDB for PostgreSQL长记忆Hooks通过httpx（Python异步HTTP客户端库）直接调用adbpgmem REST API，不依赖MCP Server，工作流程如下：

安装Hook脚本：通过pip install安装Python包，注册4个Hook CLI入口。
注册到Claude Code：通过adbpgmem-install-hooks命令将Hook脚本写入settings.json。
自动触发：Claude Code在会话启动、上下文压缩、会话结束等时机自动执行对应Hook脚本。
API调用：Hook脚本通过httpx调用adbpgmem REST API完成记忆的搜索和保存。

所有操作在后台静默执行，不影响Claude Code的正常使用。

四个Hook

Hook名称	触发事件	功能	说明
`adbpgmem-claude-context`	SessionStart	双查询搜索历史记忆，注入additionalContext	会话启动时自动加载相关知识
`adbpgmem-claude-precompact`	PreCompact	原样保存会话摘要（infer=false）	上下文压缩前保存会话快照
`adbpgmem-claude-stop`	Stop	提取会话摘要并保存到记忆库	会话结束时自动保存新知识
`adbpgmem-claude-pretooluse`	PreToolUse	阻止写入MEMORY.md等本地记忆文件	守护本地文件，重定向到长记忆服务

所有Hook在AnalyticDB for PostgreSQL长记忆服务不可达时Claude Code正常工作，不会因Hook失败而中断会话。

适用场景

适合使用Hooks集成的场景：

无感知记忆管理：您希望记忆在后台自动加载和保存，不需要手动操作。
会话启动自动加载：每次开启新会话时，自动注入历史架构决策和编码偏好。
会话结束自动保存：退出会话时自动提取并保存本次会话的有价值知识。
防止本地文件分散：阻止Claude将记忆写入MEMORY.md等本地文件，集中管理到长记忆服务。

安装Hooks

前置要求

Claude Code CLI已安装并可正常使用。
Python >= 3.10。
已获取AnalyticDB for PostgreSQL长记忆服务的API地址和Token。获取方式请参见上下文服务。
已获取adbpgmem_mcp_selfhosted项目源码adbpgmem-mcp-server-0.2.0.tar.gz。

请将压缩包解压到指定目录 adbpgmem_mcp_selfhosted，后续步骤中的路径均指向该解压目录。

安装步骤

通过pip install安装Python包，将Hook CLI入口注册到当前Python环境：

pip install -e /path/to/adbpgmem_mcp_selfhosted

-e（editable）模式将源码链接到当前环境，修改代码后无需重装即可生效。适合开发和调试阶段。如需生产部署，可去掉-e使用标准安装。

安装完成后，以下CLI命令将可用：

命令	说明
`adbpgmem-claude-context`	SessionStart Hook入口
`adbpgmem-claude-precompact`	PreCompact Hook入口
`adbpgmem-claude-stop`	Stop Hook入口
`adbpgmem-claude-pretooluse`	PreToolUse Hook入口
`adbpgmem-install-hooks`	Hook注册工具
`adbpgmem-uninstall-hooks`	Hook卸载工具

验证安装：

which adbpgmem-claude-context
# 应输出安装路径，如 /usr/local/bin/adbpgmem-claude-context

配置Hooks

Hooks支持通过环境变量或配置文件配置AnalyticDB for PostgreSQL长记忆服务，优先级从高到低：

优先级	配置来源	说明
1	环境变量	通过`export`设置
2	`$ADBPGMEM_CONFIG_DIR`	环境变量，指向配置文件所在目录
3	`./.claude/adbpgmem.conf`	项目级配置文件
4	`~/.claude/adbpgmem.conf`	全局配置文件

需要配置的参数

参数	类型	是否必选	说明
`ADBPGMEM_API_URL`	String	是	adbpgmem长记忆服务的API地址
`ADBPGMEM_API_TOKEN`	String	是	服务鉴权Token
`ADBPGMEM_USER_ID`	String	否	用户标识，默认取系统用户名

方式一：环境变量

在启动Claude Code前导出环境变量，Hooks会继承父进程的环境变量：

export ADBPGMEM_API_URL="https://api-longmemory-cn-chengdu.opentrust.net"
export ADBPGMEM_API_TOKEN="sk-your-token-here"
export ADBPGMEM_USER_ID="your.username"
claude

环境变量方式每次开新终端都需要重新设置，建议写入~/.zshrc或~/.bashrc持久化。

方式二：配置文件（推荐）

写入后无需再次操作。

全局配置（推荐，对所有项目生效）：

mkdir -p ~/.claude
cat > ~/.claude/adbpgmem.conf << 'EOF'
ADBPGMEM_API_URL="https://api-longmemory-cn-chengdu.opentrust.net"
ADBPGMEM_API_TOKEN="sk-your-token-here"
ADBPGMEM_USER_ID="your.username"
EOF

项目级配置（仅对当前项目生效）：

mkdir -p .claude
cat > .claude/adbpgmem.conf << 'EOF'
ADBPGMEM_API_URL="https://api-longmemory-cn-chengdu.opentrust.net"
ADBPGMEM_API_TOKEN="sk-your-token-here"
ADBPGMEM_USER_ID="your.username"
EOF

adbpgmem.conf包含API Token，请勿提交到Git。建议在.gitignore中添加.claude/adbpgmem.conf。配置缺失时Hooks会静默跳过执行，不影响Claude Code正常运行。

注册Hooks

安装并配置完成后，执行以下命令将4个Hook脚本注册到Claude Code的生命周期事件。

全局安装（推荐）

写入~/.claude/settings.json，对所有项目生效：

# （可选）备份现有配置
cp ~/.claude/settings.json ~/.claude/settings.json.bak 2>/dev/null

# 全局注册（自动检测平台）
adbpgmem-install-hooks --global

# 或手动指定 Claude Code 平台
adbpgmem-install-hooks --platform claude --global

项目级安装

写入<项目>/.claude/settings.json，仅对当前项目生效：

# （可选）备份现有配置
cp .claude/settings.json .claude/settings.json.bak 2>/dev/null

# 项目级注册
adbpgmem-install-hooks
# 或手动指定
adbpgmem-install-hooks --platform claude

按类型选择性安装

安装器支持按Hook职责分组选择性安装：

# 仅安装记录类 Hook（stop + precompact + pretooluse）
adbpgmem-install-hooks --global --type write

# 仅安装注入类 Hook（context）
adbpgmem-install-hooks --global --type read

# 安装全部（默认）
adbpgmem-install-hooks --global --type all

每次安装会先清除Claude Code平台下所有adbpgmem Hook，再写入指定分组，切换type时不会遗留旧配置。

注册后的配置示例：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {"type": "command", "command": "adbpgmem-claude-context", "timeout": 15}
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {"type": "command", "command": "adbpgmem-claude-precompact", "timeout": 10}
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {"type": "command", "command": "adbpgmem-claude-stop", "timeout": 30}
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit|SearchReplace",
        "hooks": [
          {"type": "command", "command": "adbpgmem-claude-pretooluse", "timeout": 2}
        ]
      }
    ]
  }
}

重复执行adbpgmem-install-hooks不会产生重复条目，会先清除已有的adbpgmem Hook再重新写入。

卸载Hooks

# 自动检测平台（推荐）
adbpgmem-uninstall-hooks --global   # 全局卸载
adbpgmem-uninstall-hooks            # 项目级卸载

# 手动指定平台
adbpgmem-uninstall-hooks --platform claude --global

卸载命令会从配置文件中移除所有adbpgmem-*开头的hook entry，并清理空的事件数组。Claude Code的Hook配置在会话启动时加载，修改后需启动新会话生效。

怎么使用Hooks

验证注册

检查Hooks是否注册成功：

cat ~/.claude/settings.json
# 应包含 adbpgmem-claude-context 等条目

功能测试：重启Claude Code，观察会话开始时是否自动加载记忆上下文。

调用方式

Hooks全自动运行，无需任何手动操作。Claude Code在以下时机自动触发：

触发时机	执行的Hook	用户感知
启动新会话	`adbpgmem-claude-context`	Claude回答时已包含历史偏好和架构决策
上下文即将压缩	`adbpgmem-claude-precompact`	无感知，后台保存会话快照
退出会话	`adbpgmem-claude-stop`	无感知，后台提取并保存会话摘要
Claude写入文件时	`adbpgmem-claude-pretooluse`	阻止写入MEMORY.md等本地记忆文件

各Hook详细工作原理

adbpgmem-claude-context（SessionStart：会话启动注入）

触发时机：每次启动Claude Code会话时。

工作流程：

读取Claude Code传入的JSON输入（包含cwd等信息）。
加载adbpgmem配置。
执行双查询搜索策略：查询1获取项目相关的架构决策，查询2获取最近的开发上下文。
对两组结果去重（按memory_id），过滤低分结果（score < 0.5）。
格式化为编号列表，通过additionalContext字段注入到Claude的会话上下文中。

输出示例：

# adbpgmem 跨会话记忆

1. 项目使用 Go 1.22 + Gin 框架，ORM 使用 GORM v2
2. 数据库选择 PostgreSQL 15，连接池用 PgBouncer，最大连接数 50
3. API 统一使用 RESTful 风格，错误码遵循 RFC 7807

adbpgmem-claude-precompact（PreCompact：上下文压缩前保存）

触发时机：Claude Code检测到上下文窗口即将满时，会触发PreCompact事件进行上下文压缩。

工作流程：

读取Claude Code传入的JSON输入（包含session_id、cwd等）。
构造会话摘要。
以infer=false方式原样保存到adbpgmem（不做原子事实提取，保留原始内容）。
附加metadata：type=compact_summary、session_id、project。

设计目的：上下文压缩会导致部分历史信息丢失，此Hook在压缩前保存快照，确保关键信息不会因压缩而永久丢失。

adbpgmem-claude-stop（Stop：会话结束保存）

触发时机：用户退出Claude Code会话时。

工作流程：

读取Claude Code传入的JSON输入（包含session_id、cwd、transcript_path等）。
读取会话transcript文件（JSONL格式的完整对话记录）。
智能摘要提取：收集所有user/assistant消息，过滤过渡性消息（< 100字符），按长度排序取top 5条，控制总预算在6000字符以内。
短会话过滤：摘要长度 < 50字符时跳过保存。
以infer=false方式保存到adbpgmem，附加metadata：type=session_summary。

设计目的：自动保存每次会话的有价值内容，无需用户手动操作，下次会话时可通过SessionStart Hook检索到。

adbpgmem-claude-pretooluse（PreToolUse：守护本地记忆文件）

触发时机：Claude调用Write/Edit/SearchReplace等文件写入工具时。

工作流程：

读取Claude Code传入的JSON输入（包含tool_name、tool_input等）。
判断是否为文件写入工具（Write/Edit/SearchReplace）。
检查目标文件路径是否匹配守护模式（MEMORY.md、memory.md、.claude/memory/）。
匹配则同时返回decision: "block"和hookSpecificOutput.permissionDecision: "deny"，阻止写入。
不匹配则放行，允许正常写入。

设计目的：防止Claude将记忆分散写入本地文件，确保所有记忆集中存储到长记忆服务，便于跨会话检索和管理。

典型场景使用案例

场景一：新会话自动继承历史决策

背景：您在项目中确定了技术栈选型，下次开启新会话时希望Claude自动知晓。

会话1（通过MCP工具或其他方式保存了记忆）：

你: 记住：项目使用 Python 3.11 + FastAPI，数据库 PostgreSQL 15，缓存 Redis 7

会话2（几天后启动新会话）：

启动 Claude Code
← adbpgmem-claude-context 自动触发
← 双查询搜索历史记忆
← 将匹配的记忆注入 additionalContext

你: 帮我添加一个新的 API 端点

Claude: 基于项目的 FastAPI + PostgreSQL 15 技术栈，我来创建新的端点...
       [自动使用正确的框架和数据库版本]

用户无需手动告知Claude技术栈，历史记忆已自动注入。

场景二：长对话上下文压缩不丢失关键信息

背景：您在进行一个复杂的系统重构，对话已经很长，Claude Code需要进行上下文压缩。

过程：

[长时间的重构对话，涉及多个架构决策和代码改动]

Claude Code 检测到上下文即将满
← adbpgmem-claude-precompact 自动触发
← 保存会话摘要到长记忆服务（infer=false，原样保存）

上下文压缩后对话继续...

你: 我们之前确定的缓存策略是什么？

Claude: 根据之前保存的信息，我们确定的缓存策略是...

关键架构决策不会因上下文压缩而永久丢失。

场景三：会话结束自动保存开发经验

背景：您在一次会话中解决了一个棘手的并发问题。

过程：

你: 这个 goroutine 死锁问题怎么排查？

Claude: [分析代码，定位问题，提供解决方案]
       问题原因是 channel 的读写顺序不一致导致死锁。
       解决方案：使用 select + context 超时机制...

[会话结束，退出 Claude Code]
← adbpgmem-claude-stop 自动触发
← 读取会话 transcript 文件
← 智能提取对话中的关键信息（过滤噪音，保留实质内容）
← 保存会话摘要到 adbpgmem（metadata: type=session_summary）

下次遇到类似的并发问题时，SessionStart Hook会自动加载这次的经验。