persistent-memory

Original：🇨🇳 Chinese

Translated

Universal Cross-session Memory Protocol (Universal Memory Protocol). Enable all AI programming tools to share the same memory system. Applicable to Claude Code / Cursor / Aider / Cline / Codex / Trae / OpenCode. Capabilities: Intelligent Classification / FSRS Decay / Monthly Compression / Multi-layer Retrieval. Triggers: User says "remember"; asks "previous"; sensitive information detected; session ends.

2installs

Sourcenangongwentian-fe/agent-skills

Added on2026-03-17

NPX Install

npx skill4agent add nangongwentian-fe/agent-skills persistent-memory

SKILL.md Content (Chinese)

View Translation Comparison →

Persistent Memory — Universal Memory Protocol

Quick Start

bash

# 首次初始化（详见 references/setup.md）
mkdir -p ~/.persistent-memory/{memories,journal,archive,.sensitive}

Core Principles

User says "remember" = Classify and write immediately
All writes must update INDEX.md
Automatically detect information type → Write to corresponding category file
Sensitive information → .sensitive/ directory (not synced)
Regular decay check + Monthly compression and archiving

File Structure

~/.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

Type	File	Writing Example
Facts	memories/facts.md	Accounts, configurations, tech stack versions, IP addresses
Decisions	memories/decisions.md	Architecture selection, technical solutions, reasons for choosing A over B
Preferences	memories/preferences.md	Coding style, tool habits, "always use pnpm"
Context	memories/context.md	Project background, business logic, team information
User Profile	SOUL.md	Personality, communication style, address, work style
Daily	journal/YYYY-MM-DD.md	Tasks completed today, problems found, temporary notes

Session Start

bash

# 必须读取
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

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

Trigger Scenarios

Trigger	Action
User says "remember xxx"	Determine category → Write → Update INDEX
User asks "how was it before"	Three-layer retrieval (see retrieval.md)
API key/account detected	Prompt user whether to record to .sensitive/
Important task completed	Prompt to record to journal/
Session ends	Update access count → Update INDEX → Write to journal
First day of each month	Prompt for monthly compression (see intelligence.md)

Writing Process (4 Steps)

Determine Category: Judge which category the content belongs to: facts/decisions/preferences/context/journal
Generate Entry: Create entry ID (format
```
X-YYYYMMDD-NNN
```
) + metadata (date/importance/tags)
Write to File: Append to the corresponding category file
Update INDEX: Rewrite INDEX.md (update statistics, recent additions, category summaries)

Entry Format

markdown

### [F-20260228-001] Title
- **Created**: 2026-02-28
- **Last Accessed**: 2026-02-28
- **Access Count**: 1
- **Importance**: high|medium|low
- **Tags**: tag1, tag2

Content...

ID Rules

```
F
```
= Facts,
```
D
```
= Decisions,
```
P
```
= Preferences,
```
C
```
= Context
Format:
```
[Type]-[YYYYMMDD]-[Daily Serial Number]
```

Backward Compatibility

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)