EN 中文

# Memory System (L / M / S)

# 记忆系统 (L / M / S)

Three-tier memory that persists knowledge across sessions.

跨会话持久化知识的三层记忆系统。

Unlike session history (which saves raw message logs), memory captures curated decisions, preferences, and project conventions so the agent doesn't start from zero every time.

与会话历史（保存原始消息日志）不同，记忆捕获经过筛选的决策、偏好和项目约定，使 agent 不必每次从零开始。

## Architecture Overview

## 架构概览

    L  Long-term / Soul     ~/.seek/soul.md
       Cross-project user preferences, thinking habits.
       Resident in system prompt (~500 token hard cap).
       Written by `seek -dream` → user review.
                            ↑ Dream (M → L distillation)
    M  Mid-term / Project   ~/.seek/projects/<hash>/memory.jsonl
       Key decisions + rationale per project.
       Index injected into every prompt;
       full content fetched on demand via `memory_recall`.
                            ↑ Distill (S → M)
    S  Short-term / Session ~/.local/share/seek/sessions/<id>.jsonl
       Full message history (auto-save).
       `/distill` at session end extracts reusable decisions into M.

## Agent Tools (M-layer)

## Agent 工具（M 层）

Tool | 工具 | Purpose | 用途
--- | --- | --- | ---
memory_observe | Save a new observation. Async V4-Flash dedup + value check. Overwrites by name. | 保存新观察。异步 V4-Flash 去重 + 价值检查。同名覆盖。
memory_remember | Same as observe but requires inline user y/N confirmation per call. | 同 observe，但每次需要用户 y/N 确认。
memory_recall | Fetch full content by name, or search by query substring. Bumps recall count on name lookup. | 按名称获取完整内容，或按子串搜索。名称查询会提升召回计数。
memory_amend | Append to an existing entry's rationale. Preserves original + timestamps new content. | 追加到现有条目的说明中。保留原文 + 新内容时间戳。
memory_archive | Move an entry to archive. Removed from active M-index, preserved in archived.jsonl. | 归档条目。从活跃 M 索引移除，保留在 archived.jsonl。

## User Commands

## 用户命令

### TUI Slash Commands

### TUI 斜杠命令

Command | What it does | 功能
--- | --- | ---
/distill | Extract ≤3 project decisions from session → user y/n/e review → M layer | 从会话提炼 ≤3 条项目决策 → 用户审查 → 写入 M 层
/memory list | List all active M entries for current project | 列出当前项目所有活跃 M 条目
/memory show | Show full content of one entry | 显示条目完整内容
/memory search | Search entries by tagline/tags | 按标签搜索条目
/memory archive | Archive a stale entry (with --reason) | 归档过期条目（带 --reason）

### CLI

### 命令行

    $ seek -dream                      # Read-only M→L scan (show candidates)
    $ seek -dream --write              # Generate + append to ~/.seek/soul.md
    $ seek memory list                  # List active entries (project at cwd)
    $ seek memory show <name>
    $ seek memory search <query>
    $ seek memory archive <name> --reason "..."

## Forgetting (Decay-Score GC)

## 遗忘机制（衰减分数 GC）

M entries have a decay score that drops with time and low recall activity. The GC pass runs at session start:

M 条目具有衰减分数，随时间和低召回活动而下降。GC 在会话启动时运行：

- Grace period: first 7 days — score stays at 1.0
- Staleness threshold: score drops below 0.50 → excluded from M-index
- Hard delete: stale for ≥60 days → moved to `archived.jsonl`

This prevents M-index bloat while keeping truly unused entries recoverable.

这防止 M 索引膨胀，同时保留真正未使用的条目可恢复。

## Storage Locations

## 存储位置

Layer | 层 | Path | Format
--- | --- | --- | ---
L (Soul) | `~/.seek/soul.md` | Plain Markdown + frontmatter
M (Project) | `~/.seek/projects/<hash>/memory.jsonl` | JSONL
M Archive | `~/.seek/projects/<hash>/archived.jsonl` | JSONL

📖 Full design rationale in docs/prd/v1.md. 📖 完整设计原理见 docs/prd/v1.md。