在上一篇里我们看了 Headroom 的 CCR压缩时把原文按哈希缓存在本地。模型觉得信息不够，就拿着哈希把原文取回来。它管的是「一次会话内」的信息不丢。按理说，这一篇我们看对了两块和「记住事情」有关的能力：一个是跨会话、跨 agent 的共享记忆。你在 Claude Code 里定过的偏好、积累的经验，能不能让 Codex、Gemini 下次也用上；另一个是 headroom learn它会翻你过去的编程会话记录。自动找出反复踩的坑，把纠正写进各 agent 的上下文文件里。这两块的源码分别在 headroom/memory/ 和 headroom/learn/ 目录下。

headroom memory：跨 agent 的共享记忆

使用者痛点：不同项目、不同 LLM之间的偏好和经验往往无法共享，每次重新配置或重复犯一样错误导致生产力下降。

在第二篇的学习里我们其实已经见过记忆的命令了运行 headroom wrap claude --memory代理会在流量里自动注入和提取记忆，什么都不用改。想在自己的代码里用，库提供了一个包装函数 with_memory

from openai import OpenAI
from headroom import with_memory
# 一行套上，之后照常使用
client = with_memory,user_id="alice")
# 第一个会话：随口告诉它你的偏好
client.chat.completions.create(
model="gpt-4o"。messages=
)
# 之后换一个全新会话：
client.chat.completions.create(
model="gpt-4o",messages=
)
# 回答会引用上个会话记下的 Python 偏好

效果就是这方面，第一个会话里你只随口说了句偏好，新会话里模型就能据此回答。这背后 with_memory 在每次调用里做了三件事：

第一件事这方面。注入相关记忆

按当前使用者消息做语义检索，把查到的相关记忆拼进消息发给模型。老实说，拼的位置有讲究，不是塞进程序提示词，而是拼到第一条使用者消息里。程序提示词是缓存热区，动了会让 prompt cache 整段失效。这和之前的 CacheAligner 是同一个考量。

再看第二件事，指导模型如何记忆

Headroom 会在程序提示词里加一段固定指令。大意是如果这轮对话里有值得长期记住的事实就在回答之后输出一个 块；话说回来，寒暄、一次性问题、已经知道的信息不要记。格式是 XML 包裹 JSON，例如：

{"memories": }

如果没有可记内容。则返回空数组 {"memories": }。

从第三件事来看，解析并保存记忆

Headroom 拿到响应后把这个块解析出来逐条调 add 存进记忆库；接下来把块从响应里剥掉再返回，你看到的回答是干净的。按理说，这整个提取内联在同一次调用里完成，没有额外的 API 调用。

使用者痛点：手动管理记忆文件繁琐且易出错，需要统一命令行工具来查看、导出与清理。

Memory 命令行示例：

headroom memory list # 看存了哪些记忆
headroom memory list --scope USER # 只看 user 级的
headroom memory list --since 7d # 最近 7 天的
headroom memory stats # 统计
headroom memory export --output backup.json # 导出备份
headroom memory prune --older-than 30d # 清理 30 天前的

分层记忆

Add 是主要入口，它所在类为 HierarchicalMemory负责统一管理持久化存储、向量索引、全文索引还有缓存等组件。一条记忆进入程序的大致流程如下：

async def add(self,content,user_id,session_id=None,agent_id=None,turn_id=None,importance=,...,auto_bubble=None):
memory = Memory(content=content,user_id=user_id,session_id=session_id,agent_id=agent_id,turn_id=turn_id,importance=importance。...)
if auto_embed:
memory.embedding = await self._embedder.embed # 生成向量
await self._store.save # 落库
if memory.embedding is not None:
await self._vector_index.index # 建向量索引
await self._index_for_text_search # 建全文索引
should_bubble = auto_bubble if auto_bubble is not None else self._config.auto_bubble
if should_bubble:
await self._maybe_bubble # 关键记忆上浮
return memory

Pain Point：不同业务场景需要灵活切换向量模型或存储后端，但默认实现已提供插件化入口。不过，

The combination of vector and full‑text indexes yields a hybrid retrieval system that can handle both semantic similarity and exact keyword matches.

分层作用域与上浮机制

The signature of Add:

def add(self。content,user_id,session_id=None,agent_id=None,turn_id=None,importance=...,...):
...
The presence of User → Session → Agent → Turn a hierarchy enables fine‑grained control:


User level: 跨所有会话持久。

Sessi on level: 仅当前对话可见。

Agent level: 针对同一对话中的特定 Agent 实例。

Turn level: 单次 LLM 调用产生。\
The “bubble” logic automatically promotes memories whose importance  exceeds a threshold to broader User scope so that valuable facts survive beyond session y originated in.

记忆的双向同步
Pain Point:手动编辑项目上下文文件容易忘掉或冲突，需要自动同步机制保持一致性。


The synchronization logic lives in bridge.py → MemoryBridge . It reads newly created organic memories and writes m back into project’s dedicated MEMORY.md file surrounded by markers.

async def sync -> SyncStats:
new_memories = await self _get_new_organic_memories
if new_memories and paths :
self _sync_state = datetime .now.isoformat
self _save_sync_state
...
async def _get_new_organic_memories:
...
if metadata .get == self _config.source_tag :
continue # 跳过从 md 导入过来的记录

各 Agent 的写入器
Writer classes use explicit markers to delimit editable region:
python
MARKER_START = ""
MARKER_END = ""
def export:
ranked = sorted
formatted = self.format_memories
section = f"{MARKER_START}
{formatted}
{MARKER_END}"
full_content = _merge_section # 替换标识块内部内容
Only two methods need implementation per subclass:


`format_memories` – decides how memories are rendered .

`default_path` – returns concrete markdown file location for each Agent . 
\
**Claude writer example**
python
def format_memories -> str:
lines =
grouped: dict]={}
for m in memories:
grouped.append
for heading,entries in grouped.items:
lines.append
for entry in entries:
lines.append
lines.append


return "
".join

def defaultpath -> Path:
if self _memorydir:
return self memorydir / "MEMORY.md"
sanitized = encodeclaudeproject_path
return Path.home / ".claude" / "projects" / sanitized / "memory" / "MEMORY.md"


Or writers follow same pattern but target different file formats such as .cursor/rules/*.mdc with YAML front‑matter.