Back to Details

persistent-memory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Persistent Memory — 通用记忆协议

Persistent Memory — Universal Memory Protocol

Quick Start

Quick Start

bash
undefined
bash
undefined

首次初始化（详见 references/setup.md）

首次初始化（详见 references/setup.md）

mkdir -p ~/.persistent-memory/{memories,journal,archive,.sensitive}
undefined
mkdir -p ~/.persistent-memory/{memories,journal,archive,.sensitive}
undefined

核心原则

Core Principles

  1. 用户说"记住" = 立刻分类写入
  2. 所有写入必须更新 INDEX.md
  3. 自动检测信息类型 → 写入对应分类文件
  4. 敏感信息 → .sensitive/ 目录（不同步）
  5. 定期衰减检查 + 月度压缩归档
  1. User says "remember" = Classify and write immediately
  2. All writes must update INDEX.md
  3. Automatically detect information type → Write to corresponding category file
  4. Sensitive information → .sensitive/ directory (not synced)
  5. Regular decay check + Monthly compression and archiving

文件结构

File Structure

~/.persistent-memory/
├── INDEX.md              # 记忆索引（AI 首先读取）
├── MEMORY.md             # 核心长期记忆（精炼摘要）
├── SOUL.md               # 用户画像/偏好
├── HEARTBEAT.md          # 心跳清单
├── memories/
│   ├── facts.md          # 事实：账号、配置、技术栈
│   ├── decisions.md      # 决策：架构选型、技术方案
│   ├── preferences.md    # 偏好：编码风格、工具习惯
│   └── context.md        # 上下文：项目背景、业务逻辑
├── journal/
│   └── YYYY-MM-DD.md     # 每日日志
├── archive/
│   └── YYYY-MM.md        # 月度压缩归档
└── .sensitive/            # 敏感信息（gitignored）
~/.persistent-memory/
├── INDEX.md              # Memory Index (read first by AI)
├── MEMORY.md             # Core long-term memory (refined summary)
├── SOUL.md               # User profile/preferences
├── HEARTBEAT.md          # Heartbeat checklist
├── memories/
│   ├── facts.md          # Facts: accounts, configurations, tech stacks
│   ├── decisions.md      # Decisions: architecture selection, technical solutions
│   ├── preferences.md    # Preferences: coding style, tool habits
│   └── context.md        # Context: project background, business logic
├── journal/
│   └── YYYY-MM-DD.md     # Daily journal
├── archive/
│   └── YYYY-MM.md        # Monthly compressed archive
└── .sensitive/            # Sensitive information (gitignored)

记忆分类速查

Quick Reference for Memory Classification

类型文件写入示例
事实memories/facts.md账号、配置、技术栈版本、IP 地址
决策memories/decisions.md架构选型、技术方案、为什么选 A 不选 B
偏好memories/preferences.md代码风格、工具习惯、"总是用 pnpm"
上下文memories/context.md项目背景、业务逻辑、团队信息
用户画像SOUL.md性格、沟通风格、称呼、工作方式
每日journal/YYYY-MM-DD.md今天完成的事、发现的问题、临时笔记
TypeFileWriting Example
Factsmemories/facts.mdAccounts, configurations, tech stack versions, IP addresses
Decisionsmemories/decisions.mdArchitecture selection, technical solutions, reasons for choosing A over B
Preferencesmemories/preferences.mdCoding style, tool habits, "always use pnpm"
Contextmemories/context.mdProject background, business logic, team information
User ProfileSOUL.mdPersonality, communication style, address, work style
Dailyjournal/YYYY-MM-DD.mdTasks completed today, problems found, temporary notes

会话开始

Session Start

bash
undefined
bash
undefined

必须读取

必须读取

cat ~/.persistent-memory/INDEX.md cat ~/.persistent-memory/MEMORY.md
cat ~/.persistent-memory/INDEX.md cat ~/.persistent-memory/MEMORY.md

可选读取

可选读取

cat ~/.persistent-memory/SOUL.md cat ~/.persistent-memory/journal/$(date +%Y-%m-%d).md 2>/dev/null

读取后告知用户：「已加载你的记忆，共 X 条长期记忆，今日已有 Y 条日志」
cat ~/.persistent-memory/SOUL.md cat ~/.persistent-memory/journal/$(date +%Y-%m-%d).md 2>/dev/null

After reading, inform the user: "Your memory has been loaded, with X long-term memories and Y today's logs recorded"

触发场景

Trigger Scenarios

触发行为
用户说"记住xxx"判断分类 → 写入 → 更新 INDEX
用户问"之前怎样"三层检索（见 retrieval.md）
检测到 API key/账号提示用户是否记录到 .sensitive/
完成重要任务提示记录到 journal/
会话结束更新访问计数 → 更新 INDEX → 写 journal
每月首日提示月度压缩（见 intelligence.md）
TriggerAction
User says "remember xxx"Determine category → Write → Update INDEX
User asks "how was it before"Three-layer retrieval (see retrieval.md)
API key/account detectedPrompt user whether to record to .sensitive/
Important task completedPrompt to record to journal/
Session endsUpdate access count → Update INDEX → Write to journal
First day of each monthPrompt for monthly compression (see intelligence.md)

写入流程（4 步）

Writing Process (4 Steps)

  1. 判断分类：根据内容判断属于 facts/decisions/preferences/context/journal
  2. 生成条目：创建条目 ID（格式 
    X-YYYYMMDD-NNN
    ）+ 元数据（日期/重要度/标签）
  3. 写入文件：追加到对应分类文件
  4. 更新 INDEX：重写 INDEX.md（更新统计、最近新增、分类摘要）
  1. Determine Category: Judge which category the content belongs to: facts/decisions/preferences/context/journal
  2. Generate Entry: Create entry ID (format 
    X-YYYYMMDD-NNN
    ) + metadata (date/importance/tags)
  3. Write to File: Append to the corresponding category file
  4. Update INDEX: Rewrite INDEX.md (update statistics, recent additions, category summaries)

条目格式

Entry Format

markdown
undefined
markdown
undefined

[F-20260228-001] 标题

[F-20260228-001] Title

  • 创建: 2026-02-28
  • 最近访问: 2026-02-28
  • 访问次数: 1
  • 重要度: high|medium|low
  • 标签: tag1, tag2
正文内容...
undefined
  • Created: 2026-02-28
  • Last Accessed: 2026-02-28
  • Access Count: 1
  • Importance: high|medium|low
  • Tags: tag1, tag2
Content...
undefined

ID 规则

ID Rules

  • F
    = Facts, 
    D
    = Decisions, 
    P
    = Preferences, 
    C
    = Context
  • 格式：
    [类型]-[YYYYMMDD]-[当日序号]
  • F
    = Facts, 
    D
    = Decisions, 
    P
    = Preferences, 
    C
    = Context
  • Format: 
    [Type]-[YYYYMMDD]-[Daily Serial Number]

向后兼容

Backward Compatibility

会话开始时自动检测：
  • INDEX.md 存在 → 新版，正常流程
  • 仅 MEMORY.md + memory/ 目录 → 旧版，提示迁移（见 migration.md）
  • 都没有 → 新用户，引导初始化（见 setup.md）
Automatically detect at session start:
  • INDEX.md exists → New version, normal process
  • Only MEMORY.md + memory/ directory exists → Old version, prompt migration (see migration.md)
  • Neither exists → New user, guide initialization (see setup.md)

更多内容（渐进式披露）

More Content (Progressive Disclosure)

  • 首次安装: references/setup.md
  • 日常工作流: references/workflow.md
  • 记忆智能（分类/衰减/压缩）: references/intelligence.md
  • 检索策略: references/retrieval.md
  • 命令参考: references/commands.md
  • 多工具适配: references/adapters/overview.md
  • 数据迁移: references/migration.md
  • GitHub 云同步: references/sync.md
  • First-time Installation: references/setup.md
  • Daily Workflow: references/workflow.md
  • Memory Intelligence (Classification/Decay/Compression): references/intelligence.md
  • Retrieval Strategy: references/retrieval.md
  • Command Reference: references/commands.md
  • Multi-tool Adaptation: references/adapters/overview.md
  • Data Migration: references/migration.md
  • GitHub Cloud Sync: references/sync.md