memory-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Memory Management

内存管理

Tiered memory system that makes an AI agent a continuous collaborator across sessions.

让AI Agent在多个会话中成为持续协作伙伴的分层内存系统。

Architecture

架构

The memory system has six tiers, configurable per project:

Tier 1: HOT CACHE (always loaded at boot -- ~200 lines target)
+-- <primer_file>             Role, identity, constraints
+-- <boot_digest_file>        Tactical status, active tasks
+-- <boot_contract_file>      Immutable constraints
+-- <snapshot_file>           Cognitive Hologram (1 sentence per file)

Tier 2: RLM SUMMARY LEDGER (fast keyword lookup -- loaded on demand)
+-- <summary_cache_file>      Pre-generated text summaries: docs, protocols, research
                              Plugin: rlm-factory | Skill: rlm-search | Profile: project
+-- <tool_cache_file>         Pre-generated text summaries: plugins, skills, scripts
                              Plugin: rlm-factory | Skill: rlm-search | Profile: tools

Tier 3: VECTOR STORE (semantic embedding search -- loaded on demand)
+-- <vector_db_backend>       ChromaDB via vector-db plugin / vector-db-agent skill
                              Profile: knowledge | Port: configured in vector_profiles.json

Tier 4: DEEP STORAGE (filesystem -- authoritative source, loaded on demand)
+-- <domain_data_dir>/        Research topics: {topic}/analysis.md
+-- <design_docs_dir>/        ADRs, RFCs
+-- <governance_dir>/         Protocols, playbooks

Tier 5: VAULT (Obsidian -- linked knowledge graph, loaded on demand)
+-- <vault_dir>/              Plugin: obsidian-integration
                              Skills: obsidian-vault-crud, obsidian-canvas-architect,
                                      obsidian-graph-traversal, obsidian-bases-manager
                              Env: VAULT_PATH or OBSIDIAN_VAULT_PATH

Tier 6: SOUL (external persistence -- optional, synced at session seal)
+-- <traces_file>             Plugin: project-specific (e.g. huggingface-utils)
                              e.g. lineage/, data/, soul_traces.jsonl on HF Hub

Projects define their own file paths for each slot. Tiers may be omitted or added based on project complexity.

该内存系统包含六个层级，可按项目进行配置：

Tier 1: HOT CACHE（启动时始终加载 -- 目标约200行）
+-- <primer_file>             角色、身份、约束条件
+-- <boot_digest_file>        战术状态、活跃任务
+-- <boot_contract_file>      不可变约束
+-- <snapshot_file>           认知全息图（每个文件一句话）

Tier 2: RLM SUMMARY LEDGER（快速关键词查找 -- 按需加载）
+-- <summary_cache_file>      预生成的文本摘要：文档、协议、研究
                              Plugin: rlm-factory | Skill: rlm-search | Profile: project
+-- <tool_cache_file>         预生成的文本摘要：插件、技能、脚本
                              Plugin: rlm-factory | Skill: rlm-search | Profile: tools

Tier 3: VECTOR STORE（语义嵌入搜索 -- 按需加载）
+-- <vector_db_backend>       通过vector-db插件 / vector-db-agent skill实现的ChromaDB
                              Profile: knowledge | Port: 在vector_profiles.json中配置

Tier 4: DEEP STORAGE（文件系统 -- 权威来源，按需加载）
+-- <domain_data_dir>/        研究主题：{topic}/analysis.md
+-- <design_docs_dir>/        ADR、RFC
+-- <governance_dir>/         协议、操作手册

Tier 5: VAULT（Obsidian -- 关联知识图谱，按需加载）
+-- <vault_dir>/              Plugin: obsidian-integration
                              Skills: obsidian-vault-crud, obsidian-canvas-architect,
                                      obsidian-graph-traversal, obsidian-bases-manager
                              Env: VAULT_PATH 或 OBSIDIAN_VAULT_PATH

Tier 6: SOUL（外部持久化 -- 可选，会话结束时同步）
+-- <traces_file>             Plugin: 项目专属插件（如huggingface-utils）
                              示例：HF Hub上的lineage/、data/、soul_traces.jsonl

项目可为每个层级定义自己的文件路径。可根据项目复杂度省略或添加层级。

Lookup Flow (3-Phase Search Protocol)

查询流程（三阶段搜索协议）

When searching for information, ALWAYS escalate in order. Never skip ahead.

Query arrives ->
1. HOT CACHE                     Instant. Boot files cover ~90% of context needs.
2. DEEP STORAGE (topic/decision) Load specific domain dir or design doc by subject.
3. RLM SUMMARY LEDGER (Phase 1)  Keyword search via query_cache.py.
4. VECTOR STORE (Phase 2)        Semantic search via query.py + ChromaDB.
5. GREP / EXACT SEARCH (Phase 3) rg/grep scoped to paths from Steps 3 or 4.
6. Ask user                      Unknown? Learn it and persist it.

搜索信息时，必须按顺序逐步升级，不得跳过前面的阶段。

查询请求到达 ->
1. HOT CACHE                     即时响应。启动文件可覆盖约90%的上下文需求。
2. DEEP STORAGE（主题/决策）     根据主题加载特定领域目录或设计文档。
3. RLM SUMMARY LEDGER（第一阶段） 通过query_cache.py进行关键词搜索。
4. VECTOR STORE（第二阶段）       通过query.py + ChromaDB进行语义搜索。
5. GREP / 精确搜索（第三阶段）    针对步骤3或4得到的路径执行rg/grep搜索。
6. 询问用户                      无匹配结果？学习该内容并持久化存储。

Phase 1 -- RLM Summary Scan (Table of Contents)

第一阶段 -- RLM摘要扫描（目录索引）

RLM is amortized prework: each file read ONCE, summarized ONCE, cached as plain text JSON. Searching summaries is O(1) keyword lookup -- no embeddings, no inference.

bash

python3 plugins/rlm-factory/skills/rlm-search/scripts/query_cache.py \
  --profile plugins "what does the vector query tool do"

python3 plugins/rlm-factory/skills/rlm-search/scripts/query_cache.py \
  --profile project --list

Use Phase 1 when: You need to understand what a file does, find which file owns a feature, or navigate the codebase without reading individual files.

Escalate to Phase 2 when: The summary is insufficient or no match found.

RLM是预计算的分摊工作：每个文件仅读取一次、摘要一次，以纯文本JSON格式缓存。搜索摘要为O(1)级别的关键词查找 -- 无需嵌入、无需推理。

bash

python3 plugins/rlm-factory/skills/rlm-search/scripts/query_cache.py \
  --profile plugins "what does the vector query tool do"

python3 plugins/rlm-factory/skills/rlm-search/scripts/query_cache.py \
  --profile project --list

适用场景：需要了解文件功能、查找负责某功能的文件，或无需读取单个文件即可浏览代码库时。

升级到第二阶段的时机：摘要信息不足或未找到匹配结果时。

Phase 2 -- Vector Store Semantic Search (Back-of-Book Index)

第二阶段 -- Vector Store语义搜索（书后索引）

Embedding-based nearest-neighbor search across all indexed chunks. Returns ranked parent chunks with RLM Super-RAG context pre-injected.

bash

python3 plugins/vector-db/skills/vector-db-agent/scripts/query.py \
  "nearest-neighbor embedding search implementation" \
  --profile knowledge --limit 5

Use Phase 2 when: You need specific code snippets, patterns, or implementations.

Escalate to Phase 3 when: You have a file path (from Phase 1 or 2) and need an exact line.

基于嵌入的最近邻搜索，覆盖所有已索引的内容块。返回已预注入RLM Super-RAG上下文的排序父内容块。

bash

python3 plugins/vector-db/skills/vector-db-agent/scripts/query.py \
  "nearest-neighbor embedding search implementation" \
  --profile knowledge --limit 5

适用场景：需要特定代码片段、模式或实现细节时。

升级到第三阶段的时机：已从第一或第二阶段获取到文件路径，需要查找精确行内容时。

Phase 3 -- Grep / Exact Search (Ctrl+F)

第三阶段 -- Grep / 精确搜索（Ctrl+F）

Precise keyword or regex match. Always scope to paths discovered in earlier phases.

bash

undefined

精确的关键词或正则匹配。始终限定在前期阶段发现的路径范围内。

bash

undefined

Scoped to a specific path (use paths from Phase 1/2)

限定在特定路径（使用第一/第二阶段得到的路径）

grep_search "VectorDBOperations" plugins/vector-db/skills/

Ripgrep for regex

使用Ripgrep进行正则搜索

rg "def query" plugins/vector-db/ --type py


**Anti-patterns:** Never run a full-repo grep without scoping. Never skip Phase 1.

rg "def query" plugins/vector-db/ --type py


**反模式**：永远不要在未限定范围的情况下执行全仓库grep搜索。永远不要跳过第一阶段。

Dependencies

依赖项

rlm-factory

-- RLM Summary Ledger (Tier 2)

rlm-factory

-- RLM摘要账本（第二层级）

Component	Value
Plugin	`plugins/rlm-factory/`
Skill (write)	`skills/rlm-curator/` -- distill, inject, audit, cleanup
Skill (read)	`skills/rlm-search/` -- query the ledger
Script: Phase 1 search	`skills/rlm-search/scripts/query_cache.py`
Script: inject summary	`skills/rlm-curator/scripts/inject_summary.py`
Script: audit coverage	`skills/rlm-curator/scripts/inventory.py`
Script: shared config	`skills/rlm-curator/scripts/rlm_config.py`
Cache files	`.agent/learning/rlm_summary_cache.json` (docs), `.agent/learning/rlm_tool_cache.json` (tools)

组件	取值
Plugin	`plugins/rlm-factory/`
Skill（写入）	`skills/rlm-curator/` -- 提炼、注入、审计、清理
Skill（读取）	`skills/rlm-search/` -- 查询账本
脚本：第一阶段搜索	`skills/rlm-search/scripts/query_cache.py`
脚本：注入摘要	`skills/rlm-curator/scripts/inject_summary.py`
脚本：审计覆盖范围	`skills/rlm-curator/scripts/inventory.py`
脚本：共享配置	`skills/rlm-curator/scripts/rlm_config.py`
缓存文件	`.agent/learning/rlm_summary_cache.json` （文档）、 `.agent/learning/rlm_tool_cache.json` （工具）

vector-db

-- Vector Store (Tier 3)

vector-db

-- Vector Store（第三层级）

Component	Value
Plugin	`plugins/vector-db/`
Skill	`skills/vector-db-agent/` -- ingest, query, operations
Script: Phase 2 search	`skills/vector-db-agent/scripts/query.py`
Script: ingest files	`skills/vector-db-agent/scripts/ingest.py`
Script: operations	`skills/vector-db-agent/scripts/operations.py`
Script: config	`skills/vector-db-agent/scripts/vector_config.py`
Backend	ChromaDB ( `chromadb.HttpClient` with `PersistentClient` fallback)

组件	取值
Plugin	`plugins/vector-db/`
Skill	`skills/vector-db-agent/` -- 摄入、查询、操作
脚本：第二阶段搜索	`skills/vector-db-agent/scripts/query.py`
脚本：摄入文件	`skills/vector-db-agent/scripts/ingest.py`
脚本：操作	`skills/vector-db-agent/scripts/operations.py`
脚本：配置	`skills/vector-db-agent/scripts/vector_config.py`
后端	ChromaDB（ `chromadb.HttpClient` ， fallback为 `PersistentClient` ）

obsidian-integration

-- Linked Vault (Tier 5)

obsidian-integration

-- 关联知识库（第五层级）

Component	Value
Plugin	`plugins/obsidian-integration/`
Skill: vault setup	`skills/obsidian-init/` -- prerequisites, `.obsidian/` config, exclusion filters
Skill: read/write notes	`skills/obsidian-vault-crud/` -- atomic create/read/update/append via `vault_ops.py`
Skill: markdown	`skills/obsidian-markdown-mastery/` -- wikilinks, frontmatter, callouts
Skill: canvas	`skills/obsidian-canvas-architect/` -- visual boards (JSON Canvas spec)
Skill: graph	`skills/obsidian-graph-traversal/` -- backlink and wikilink traversal
Skill: bases	`skills/obsidian-bases-manager/` -- table/grid/card views from YAML metadata
Script: CRUD	`skills/obsidian-vault-crud/scripts/vault_ops.py`
Script: parse	`obsidian-parser/parser.py` -- shared markdown parser
Requires	`pip:ruamel.yaml` (lossless YAML frontmatter), Obsidian Desktop
Env	`VAULT_PATH` -- absolute path to the vault root

组件	取值
Plugin	`plugins/obsidian-integration/`
Skill：知识库设置	`skills/obsidian-init/` -- 前置条件、 `.obsidian/` 配置、排除过滤器
Skill：读写笔记	`skills/obsidian-vault-crud/` -- 通过 `vault_ops.py` 实现原子化增删改查/追加
Skill：Markdown处理	`skills/obsidian-markdown-mastery/` -- 维基链接、前置元数据、提示框
Skill：画布管理	`skills/obsidian-canvas-architect/` -- 可视化看板（JSON Canvas规范）
Skill：图谱遍历	`skills/obsidian-graph-traversal/` -- 反向链接和维基链接遍历
Skill：视图管理	`skills/obsidian-bases-manager/` -- 基于YAML元数据的表格/网格/卡片视图
脚本：CRUD操作	`skills/obsidian-vault-crud/scripts/vault_ops.py`
脚本：解析	`obsidian-parser/parser.py` -- 共享Markdown解析器
依赖	`pip:ruamel.yaml` （无损YAML前置元数据）、Obsidian桌面端
环境变量	`VAULT_PATH` -- 知识库根目录的绝对路径

Promotion / Demotion Rules

升级/降级规则

Promote to Hot Cache when:

升级到热缓存的条件：

Knowledge is referenced in 3+ consecutive sessions
It's critical for active work (current spec, active protocol)
It's a constraint or identity anchor

知识在3个及以上连续会话中被引用
对当前工作至关重要（当前规范、活跃协议）
属于约束条件或身份锚点

Demote to Deep Storage when:

降级到深度存储的条件：

Spec/feature is completed and merged
Governing document is superseded by newer version
Topic research is concluded
Technical decision is ratified (move from draft to archive)

规范/功能已完成并合并
管理文档被新版本取代
主题研究已完成
技术决策已通过（从草稿移至归档）

What Goes Where

内容分层指南

Type	Hot Cache	On-Demand Tier
Active tasks	Boot digest	--
Identity/role	Primer file	--
Constraints	Boot contract	--
Session state	Snapshot file	Tier 6 Soul (traces)
Research topics	Summary in snapshot	Tier 4: `domain_data_dir/{name}/`
Design decisions	Referenced by ID	Tier 4: `design_docs_dir/{id}_{name}.md`
Governing docs	Referenced by ID	Tier 4: `governance_dir/{id}_{name}.md`
Plugins/scripts/tools	--	Tier 2: RLM Summary Ledger (tool cache)
Docs/protocols/research	--	Tier 2: RLM Summary Ledger (summary cache)
System docs	--	Tier 2 RLM + Tier 3 Vector Store
Linked notes, canvases	--	Tier 5: Vault (Obsidian)
External persistence	--	Tier 6: Soul (HuggingFace or equivalent)

类型	热缓存	按需加载层级
活跃任务	启动摘要	--
身份/角色	初始化文件	--
约束条件	启动契约	--
会话状态	快照文件	第六层级Soul（跟踪数据）
研究主题	快照中的摘要	第四层级： `domain_data_dir/{name}/`
设计决策	通过ID引用	第四层级： `design_docs_dir/{id}_{name}.md`
管理文档	通过ID引用	第四层级： `governance_dir/{id}_{name}.md`
插件/脚本/工具	--	第二层级：RLM摘要账本（工具缓存）
文档/协议/研究	--	第二层级：RLM摘要账本（摘要缓存）
系统文档	--	第二层级RLM + 第三层级Vector Store
关联笔记、画布	--	第五层级：Obsidian知识库
外部持久化	--	第六层级：Soul（HuggingFace或同类服务）

Session Memory Workflow

会话内存工作流

At Session Start (Boot)

会话启动时

Load hot cache files in order (primer -> contract -> digest -> snapshot)
Integrity check validates snapshot is current
If snapshot stale -> flag for refresh at session end

按顺序加载热缓存文件（初始化文件 -> 契约 -> 摘要 -> 快照）
完整性检查验证快照是否为最新版本
若快照过期 -> 标记为需在会话结束时刷新

During Session

会话进行中

New learning -> Write to
```
<domain_data_dir>/{topic}/
```
New decision -> Create design document draft
New tool -> Register in tool inventory
Correction -> Update relevant file + note in disputes log if contradicting

新学习内容 -> 写入
```
<domain_data_dir>/{topic}/
```
新决策 -> 创建设计文档草稿
新工具 -> 在工具清单中注册
修正内容 -> 更新相关文件 + 若存在矛盾则在争议日志中记录

At Session End (Seal)

会话结束时（收尾）

Update snapshot file with new content learned this session
Seal validates no drift since last audit
Persist traces to external storage (if configured)

使用本次会话学到的新内容更新快照文件
收尾操作验证自上次审计以来无内容漂移
将跟踪数据持久化到外部存储（若已配置）

Conventions

约定规范

Hot cache target: ~200 lines total across all boot files
Snapshot: 1 sentence per file, machine-readable
Topic folders:
```
lowercase-hyphens/
```
Document numbering: 3-digit, sequential
Always capture corrections and contradictions in a disputes log

热缓存目标：所有启动文件总长度约200行
快照：每个文件一句话，机器可读
主题文件夹：
```
lowercase-hyphens/
```
格式
文档编号：3位数字，按顺序分配
必须记录：争议日志中需记录所有修正内容和矛盾点

Configuration

配置

Projects configure the memory system by setting file paths in their project-specific plugin:

Variable	Purpose
`MEMORY_PRIMER_FILE`	Path to cognitive primer / role definition
`MEMORY_BOOT_DIGEST`	Path to tactical boot digest
`MEMORY_BOOT_CONTRACT`	Path to immutable constraints
`MEMORY_SNAPSHOT_FILE`	Path to learning snapshot (hologram)
`MEMORY_DOMAIN_DIR`	Directory for domain research
`MEMORY_DESIGN_DIR`	Directory for design docs (e.g. ADRs)
`MEMORY_GOVERNANCE_DIR`	Directory for governing docs (e.g. Protocols)

项目可通过在项目专属插件中设置文件路径来配置内存系统：

变量	用途
`MEMORY_PRIMER_FILE`	认知初始化文件/角色定义的路径
`MEMORY_BOOT_DIGEST`	战术启动摘要的路径
`MEMORY_BOOT_CONTRACT`	不可变约束文件的路径
`MEMORY_SNAPSHOT_FILE`	学习快照（全息图）的路径
`MEMORY_DOMAIN_DIR`	领域研究目录的路径
`MEMORY_DESIGN_DIR`	设计文档目录的路径（如ADR）
`MEMORY_GOVERNANCE_DIR`	管理文档目录的路径（如协议）

Architecture Diagrams

架构图

Diagram	What It Shows
memory_architecture.mmd	Full 4-tier memory system with exact plugin/skill/script names per tier
memory_lookup_flow.mmd	3-phase search sequence: Hot Cache -> RLM Ledger -> Vector Store -> Grep
memory_session_lifecycle.mmd	Session Boot -> Active -> Seal lifecycle with all event types

图	展示内容
memory_architecture.mmd	完整的四层内存系统，包含每个层级对应的精确插件/技能/脚本名称
memory_lookup_flow.mmd	三阶段搜索序列：热缓存 -> RLM账本 -> Vector Store -> Grep
memory_session_lifecycle.mmd	会话启动 -> 活跃 -> 收尾的完整生命周期，包含所有事件类型