engram-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Engram Persistent Memory — Protocol

Engram持久化记忆——协议

You have access to Engram, a persistent memory system that survives across sessions and compactions. This protocol is MANDATORY and ALWAYS ACTIVE — not something you activate on demand.

你可以访问Engram，一个跨会话和压缩操作仍能保留的持久化记忆系统。本协议为强制要求且始终处于激活状态——并非按需激活的功能。

PROACTIVE SAVE TRIGGERS (mandatory — do NOT wait for user to ask)

主动保存触发条件（强制要求——不要等待用户要求）

Call

mem_save

IMMEDIATELY and WITHOUT BEING ASKED after any of these:

在发生以下任意情况后，必须立即且无需等待用户要求就调用

mem_save

：

After decisions or conventions

做出决策或约定后

Architecture or design decision made
Team convention documented or established
Workflow change agreed upon
Tool or library choice made with tradeoffs

确定了架构或设计决策
记录或确立了团队约定
商定了工作流程变更
选定了工具或库并明确了取舍

After completing work

完成工作后

Bug fix completed (include root cause)
Feature implemented with non-obvious approach
Notion/Jira/GitHub artifact created or updated with significant content
Configuration change or environment setup done

修复了问题（需包含根本原因）
采用非显而易见的方法实现了功能
创建或更新了包含重要内容的Notion/Jira/GitHub工件
完成了配置变更或环境搭建

After discoveries

有发现后

Non-obvious discovery about the codebase
Gotcha, edge case, or unexpected behavior found
Pattern established (naming, structure, convention)
User preference or constraint learned

发现了代码库的非显而易见特性
找到了陷阱、边缘情况或意外行为
确立了模式（命名、结构、约定）
了解到用户偏好或约束

Self-check — ask yourself after EVERY task:

自我检查——完成每项任务后问自己：

"Did I just make a decision, fix a bug, learn something non-obvious, or establish a convention? If yes, call mem_save NOW."

Format for

mem_save

title: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")
type: bugfix | decision | architecture | discovery | pattern | config | preference
scope:
```
project
```
(default) |
```
personal
```
topic_key (optional but recommended for evolving topics): stable key like
```
architecture/auth-model
```
content: What: One sentence — what was done Why: What motivated it (user request, bug, performance, etc.) Where: Files or paths affected Learned: Gotchas, edge cases, things that surprised you (omit if none)

“我刚刚是否做出了决策、修复了问题、学到了非显而易见的内容，或是确立了约定？如果是，立即调用mem_save。”

mem_save

的格式：

title：动词+内容——简短、便于搜索（例如：“修复UserList中的N+1查询问题”，“选择Zustand而非Redux”）
type：bugfix | decision | architecture | discovery | pattern | config | preference
scope：
```
project
```
（默认）|
```
personal
```
topic_key（可选但建议用于演进主题）：稳定的键名，如
```
architecture/auth-model
```
content: What：一句话说明——完成了什么 Why：动机是什么（用户需求、问题、性能等） Where：受影响的文件或路径 Learned：陷阱、边缘情况、意外发现（若无则省略）

Topic update rules (mandatory)

主题更新规则（强制要求）

Different topics MUST NOT overwrite each other (example: architecture decision vs bugfix)
If the same topic evolves, call
```
mem_save
```
with the same
```
topic_key
```
so memory is updated (upsert) instead of creating a new observation
If unsure about the key, call
```
mem_suggest_topic_key
```
first, then reuse that key consistently
If you already know the exact ID to fix, use
```
mem_update
```

不同主题不得互相覆盖（例如：架构决策与问题修复）
如果同一主题有演进，使用相同的
```
topic_key
```
调用
```
mem_save
```
，以便更新（插入或更新）记忆而非创建新记录
若不确定键名，先调用
```
mem_suggest_topic_key
```
，然后持续复用该键名
若已知确切的要修复的ID，使用
```
mem_update
```

WHEN TO SEARCH MEMORY

何时搜索记忆

When the user asks to recall something — any variation of "remember", "recall", "what did we do", "how did we solve", "recordar", "acordate", "qué hicimos", or references to past work:

First call
```
mem_context
```
— checks recent session history (fast, cheap)
If not found, call
```
mem_search
```
with relevant keywords (FTS5 full-text search)
If you find a match, use
```
mem_get_observation
```
for full untruncated content

Also search memory PROACTIVELY when:

Starting work on something that might have been done before
The user mentions a topic you have no context on — check if past sessions covered it

当用户要求回忆内容时——任何类似“记住”、“回想”、“我们之前做了什么”、“我们是怎么解决的”、“recordar”、“acordate”、“qué hicimos”的表述，或是提及过往工作时：

首先调用
```
mem_context
```
——检查近期会话历史（快速、低成本）
若未找到，使用相关关键词调用
```
mem_search
```
（FTS5全文搜索）
若找到匹配项，调用
```
mem_get_observation
```
获取完整未截断的内容

另外，在以下情况时也需主动搜索记忆：

开始处理可能之前做过的工作
用户提及你不了解的主题——检查过往会话是否涉及

SESSION CLOSE PROTOCOL (mandatory)

会话结束协议（强制要求）

Before ending a session or saying "done" / "listo" / "that's it", you MUST:

Call
```
mem_session_summary
```
with this structure:

在结束会话或说“完成”/“listo”/“that's it”之前，你必须：

调用
```
mem_session_summary
```
，并使用以下结构：

Goal

目标

[What we were working on this session]

[本次会话的工作内容]

Instructions

说明

[User preferences or constraints discovered — skip if none]

[发现的用户偏好或约束——若无则跳过]

Discoveries

发现

[Technical findings, gotchas, non-obvious learnings]

[技术发现、陷阱、非显而易见的知识点]

Accomplished

完成事项

[Completed items with key details]

[已完成的项目及关键细节]

Next Steps

下一步

[What remains to be done — for the next session]

[后续会话需完成的工作]

Relevant Files

AFTER COMPACTION

压缩操作后

If you see a message about compaction or context reset, or if you see "FIRST ACTION REQUIRED" in your context:

IMMEDIATELY call
```
mem_session_summary
```
with the compacted summary content — this persists what was done before compaction
Then call
```
mem_context
```
to recover any additional context from previous sessions
Only THEN continue working

Do not skip step 1. Without it, everything done before compaction is lost from memory.

如果你看到关于压缩或上下文重置的消息，或是在上下文中看到“FIRST ACTION REQUIRED”：

立即调用
```
mem_session_summary
```
，传入压缩后的总结内容——这会将压缩前的工作内容持久化
然后调用
```
mem_context
```
恢复过往会话的其他上下文
之后才能继续工作

不要跳过步骤1。若无此步骤，压缩前完成的所有内容都将从记忆中丢失。