Memory Skills (CoALA-based)

Memory = Filesystem - Cognitive architecture for language agents

Based on the CoALA framework (Cognitive Architectures for Language Agents), this skill implements a complete memory system with four memory types.

Memory Architecture

                    ┌─────────────────┐
                    │  Working Memory │  ← Short-term, central hub
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ↓                    ↓                    ↓
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│   Episodic    │   │   Semantic    │   │  Procedural   │
│   情景记忆     │   │   语义记忆     │   │   程序性记忆   │
└───────────────┘   └───────────────┘   └───────────────┘
        ↑                                        ↑
    Long-term ─────────────────────────────── Long-term

Memory Types (CoALA)

Directory Structure

Global Memory (~/.claude/memory/)

Cross-project shared knowledge:

~/.claude/memory/
├── working/                    # Working Memory (可持久化的会话上下文)
│   └── {name}-context.md       # 保存的会话状态 (通过 /save-context)
│
├── procedural/                 # Procedural Memory
│   ├── preferences.md          # User preferences
│   ├── workflows.md            # Common workflows
│   └── prompts/                # Reusable prompt templates
│       └── {name}.md
│
├── semantic/                   # Semantic Memory
│   ├── learnings/              # Knowledge by topic
│   │   ├── rust-tips.md
│   │   ├── git-tips.md
│   │   └── {topic}.md
│   └── reflections/            # Insights from reflection
│       └── {date}-{insight}.md
│
├── episodic/                   # Episodic Memory
│   ├── mistakes/               # Errors and how they were fixed
│   │   └── {date}-{error}.md
│   ├── solutions/              # Successfully solved problems
│   │   └── {date}-{problem}.md
│   └── trajectories/           # Complete task execution logs
│       └── {date}-{task}.md
│
└── index.json                  # Search index (auto-generated)

Project Memory (.claude/memory/)

Project-specific knowledge:

{project}/.claude/memory/
├── semantic/
│   ├── architecture.md         # Project architecture
│   ├── conventions.md          # Coding conventions
│   └── decisions.md            # Technical decisions (ADRs)
│
├── episodic/
│   └── sessions/               # Session summaries
│       └── {date}-{topic}.md
│
└── index.json                  # Project search index

Commands

Working Memory Commands

/save-context [name] - 保存当前会话的关键上下文

触发词: "保存上下文", "save context", "保存当前状态"

# 保存到: ~/.claude/memory/working/{name}-context.md 或 .claude/memory/working/

## Session Context: {name}
**Saved**: {timestamp}

### Current Goals
- {what we're trying to accomplish}

### Key Decisions Made
- {important decisions in this session}

### Important Context
- {critical information to remember}

### Next Steps
- {what to do when resuming}

/load-context [name] - 加载之前保存的上下文

触发词: "加载上下文", "load context", "恢复上下文", "继续之前的工作"

1. Search for context files in working/ directory
2. Display available contexts if name not specified
3. Load and summarize the selected context
4. Confirm: "已加载上下文: {name}"

Instructions for Claude

Action Space (CoALA)

You have four memory actions:

1. Retrieval (读取): Load from long-term → working memory
2. Reasoning (推理): Process in working memory
3. Learning (写入): Save from working → long-term memory
4. Forgetting (遗忘): Remove from long-term memory

When User Says "Remember" / "记住"

1. Detect memory type:

`` Content about... → Memory Type → Location ───────────────────────────────────────────────────── User preference → Procedural → procedural/preferences.md Workflow/process → Procedural → procedural/workflows.md Fact/knowledge → Semantic → semantic/learnings/{topic}.md Project architecture → Semantic → .claude/memory/semantic/architecture.md Error encountered → Episodic → episodic/mistakes/{date}-{error}.md Problem solved → Episodic → episodic/solutions/{date}-{problem}.md ``

1. Format content:

```markdown ## {YYYY-MM-DD} - {brief title}

{content}

Context: {why this is important} Tags: {relevant keywords}

```

1. Update index (if index.json exists):

``json { "entries": [ { "file": "semantic/learnings/rust-tips.md", "keywords": ["rust", "ownership", "borrow"], "updated": "2026-01-25" } ] } ``

1. Confirm: Tell user what was saved, where, and memory type

When User Says "Recall" / "回忆"

1. Search priority:

- First: Project memory .claude/memory/ - Then: Global memory ~/.claude/memory/ - Check: index.json for keyword matches - Fallback: Scan file names and content

1. Return results with metadata:

``` Found 2 relevant memories:

📁 [Semantic] ~/.claude/memory/semantic/learnings/rust-tips.md → "Use Arc<Mutex<T>> for shared mutable state..."

📁 [Episodic] .claude/memory/episodic/solutions/2026-01-20-async-bug.md → "Fixed by adding .await after spawn..." ```

1. If nothing found:

`` 没有找到关于 "{topic}" 的记忆。 → 使用 /remember 来保存新知识 ``

When User Says "Forget" / "忘记"

1. Confirm before deletion:

``` 找到以下相关记忆: - ~/.claude/memory/semantic/learnings/old-api.md

确认删除吗? (y/n) ```

1. Delete and update index

1. Confirm: "已删除关于 {topic} 的记忆"

When User Says "Reflect" / "反思"

Reflection converts episodic memories into semantic knowledge:

1. Scan recent episodic memories (last 7 days)

1. Identify patterns:

- Repeated mistakes → Learning opportunity - Multiple solutions → Best practice - Common trajectories → Workflow template

1. Generate reflection:

```markdown ## 2026-01-25 - Reflection: Async Error Handling

Pattern observed: In 3 recent sessions, async errors were caused by missing .await

Insight: Always check for missing .await when debugging async code

Source episodes: - episodic/mistakes/2026-01-20-async-bug.md - episodic/mistakes/2026-01-22-tokio-error.md - episodic/solutions/2026-01-23-fixed-spawn.md

```

1. Save to: semantic/reflections/{date}-{insight}.md

When User Says "Summarize Session" / "总结会话"

1. Gather session context:

- What was accomplished - Key decisions made - Problems encountered and solutions - New learnings

1. Generate summary:

```markdown ## 2026-01-25 - Session: Implementing Memory System

Goals: Improve memory-filesystem skill based on CoALA

Accomplished: - Added working memory support - Implemented forgetting mechanism - Added reflection capability

Key Decisions: - Used JSON for search index - Separated global vs project memory

Learnings: - CoALA has 4 memory types, not 3

```

1. Save to:

- Project: .claude/memory/episodic/sessions/{date}-{topic}.md - Or global: ~/.claude/memory/episodic/trajectories/{date}-{task}.md

Auto-Learning (Proactive)

When you discover valuable information during a session:

1. Detect learning opportunity:

- Error fixed → Potential mistake memory - New technique used → Potential learning - Repeated action → Potential workflow

1. Ask user: "发现了一个有用的技巧，要我记住吗？"

1. If confirmed: Save to appropriate memory location

Quick Reference

Example Interactions

Example 1: Remember

User: "记住：Rust 中使用 thiserror 来定义错误类型"

Claude:
1. Detect: Knowledge/fact → Semantic memory
2. Location: ~/.claude/memory/semantic/learnings/rust-tips.md
3. Append with date, tags
4. Update index.json
5. Response: "✓ 已保存到语义记忆 (rust-tips.md)"

Example 2: Reflect

User: "/reflect"

Claude:
1. Scan episodic/mistakes/ and episodic/solutions/ (last 7 days)
2. Found pattern: 3 instances of borrow checker errors
3. Generate insight: "Common cause: trying to move value after borrow"
4. Save to: semantic/reflections/2026-01-25-borrow-patterns.md
5. Response: "✓ 生成了 1 条反思，已保存到语义记忆"

Example 3: Forget

User: "忘记关于旧 API 的记忆"

Claude:
1. Search: Found semantic/learnings/old-api-v1.md
2. Confirm: "找到 1 条相关记忆，确认删除?"
3. User confirms
4. Delete file, update index
5. Response: "✓ 已删除关于旧 API 的记忆"