Long-Term Memory Management

Overview

Enable AI assistants to have persistent memory capabilities across sessions, remember user information, preferences, historical interactions and important matters, and provide personalized, continuous intelligent services.

Core Principles:

Must check configuration status first in the first conversation → guide configuration → load all memories
Continuously identify recordable information during conversations
Proactively manage memories (update, delete, associate, search)

When to Use

Use this skill when:

Users mention personal information (occupation, location, family situation)
Users express preferences (communication style, output format)
Users make important decisions or commitments
Users mention to-do items or reminders
Users share knowledge, experience or business rules
Cross-session context continuity is required

Do NOT use:

One-time conversations with no need for follow-up
Pure technical questions with no personalization needs

Quick Reference

Task	Command
Check Configuration	`python scripts/check_config.py`
Directly Write Configuration	`python scripts/check_config.py --write --api-key sk-xxx [--base-url https://...] [--model text-embedding-3-large]`
First Load	`python scripts/load_context.py --mode all`
Semantic Search	`python scripts/load_context.py --mode all --query "keywords"`
Add Long-Term Memory	`python scripts/manage_memories.py add --file <file> --title "title" --content "content"`
Search Long-Term Memory	`python scripts/manage_memories.py search --query "keywords"`
Update Long-Term Memory	`python scripts/manage_memories.py update --file <file> --title "title" --content "new content"`
Delete Long-Term Memory	`python scripts/manage_memories.py delete --file <file> --title "title"`
Add Short-Term Memory	`python scripts/manage_short_term.py add --content "content" --agent chat`
View Today's Memories	`python scripts/manage_short_term.py show`
Vector Search	`python scripts/vector_store.py query --query "keywords" --top-k 5`
Verify Installation	`python scripts/setup_check.py`

Core Workflow

1. First Conversation - Check Configuration → Guide Configuration → Load All Memories (Mandatory)

Execution Flow:

Detect user's first message
    ↓
Check configuration status (Mandatory!)
    ├─ Not configured → Guide user to configure → Load memories after configuration is completed
    └─ Configured → Directly load all memories

Step 1: Check Configuration Status

bash

python scripts/check_config.py

Configuration Status Judgment:

✅ Exists
```
configured.txt
```
→ Configuration completed
❌ Does not exist
```
configured.txt
```
→ Configuration not completed, must guide user

Step 2: Directly Write Configuration (if not completed)

bash

python scripts/check_config.py --write --api-key sk-xxx

Optional Parameters:

```
--base-url https://api.example.com
```
- API Base URL (Optional)
```
--model text-embedding-3-large
```
- Embedding Model (Optional, Default: text-embedding-3-small)

Explanation when guiding users:

"I notice the memory system hasn't been configured yet. Please provide your OpenAI API Key and I'll help you complete the configuration."

Directly write after obtaining API Key:

After the user provides the API Key, run the write command directly without requiring user confirmation.

Step 3: Load All Memories (after configuration is completed)

bash

python scripts/load_context.py --mode all

Complete Loading Process:

Detect user's first message
First check configuration status
If not configured → Guide configuration
Run loading command
Automatically archive expired short-term memories (>24 hours)
Load long-term memories + today's short-term memories
Summarize key memory points
Adjust interaction method based on memories
Start replying

Example Inner Monologue:

"User's first message, first check configuration. Configuration completed, now load memories. Loading completed, total 13 long-term memories, 2 today's short-term memories. User is a product manager working in Beijing, prefers concise replies. Okay, now can start replying."

Skipping configuration check is a serious error! Replying without loading memories is a serious error!

2. During Conversation - Invisible Recording

Core Principle: Record silently, do not interrupt the conversation flow

Usage Scenarios:

Long-term Memory: User preferences, personal information, important decisions, knowledge and experience → Use
```
manage_memories.py
```
Short-term Memory: Today's temporary information, follow-up items, inter-Agent messages → Use
```
manage_short_term.py
```

User input → Identify recordable information → Record in background → Continue normal conversation

Identification Patterns:

Information Type	User Expression Examples	Recorded to	Memory Type
Personal Information	"I'm a product manager", "I'm in Beijing"	user-profile.md	Long-term
Preference Statements	"I like concise replies", "Use tables"	user-preferences.md	Long-term
Important Decisions	"I decided to choose A", "Execute next week"	decisions-context.md	Long-term
To-do Items	"Remember to remind me", "Complete before Wednesday"	tasks-reminder.md	Long-term
Knowledge & Experience	"This process is...", "Note that..."	knowledge-base.md	Long-term
Temporary Information	"Moving next week", "Physical exam in the morning"	Short-term memory file	Short-term
Agent Messages	"Tell the health assistant the user has a physical exam"	Short-term memory file	Short-term

Correct Practice:

User: I'm a product manager and usually quite busy
      ↓
AI: (Runs manage_memories.py add --file user-profile.md ... in background)
    How do you usually like to relax?

Incorrect Practice:

❌ AI: Let me note that you're a product manager, right? Okay, recorded...
   (Interrupts conversation, ruins experience)

Do NOT ask for confirmation! Do NOT tell users you're recording! Record silently and continue the conversation!

3. Short-term Memory Expiration Assessment

Timing: Check yesterday's short-term memories (to be archived) every time memories are loaded

Core Principle: AI independently assesses and decides, no need to ask users

Assessment Process:

Check yesterday's short-term memories → AI independently identifies valuable content → Automatically transfer to long-term memory → Continue conversation

Assessment Criteria (Transfer to long-term if any of the following is met):

✅ User preferences or habits (e.g., "I like concise replies")
✅ Important personal information (e.g., "Preparing for PMP certification", "Moving to a new address")
✅ Long-term to-do items or commitments (e.g., "Exercise 3 times a week")
✅ Important knowledge or experience (e.g., "Key steps in workflow")
❌ Temporary information (completed, one-time) → Let it be archived naturally

Example:

User: (Said yesterday) I'm preparing for PMP certification and have already registered
      ↓
AI: (Checks short-term memories in background, identifies as important personal development plan)
    (Automatically runs manage_memories.py add --file tasks-reminder.md ...)
    (Continues normal conversation without mentioning the transfer operation)

Completely invisible! Do NOT ask! Do NOT tell users! AI decides independently and transfers automatically!

4. Subsequent Conversations - Load On Demand

bash

# Default Mode (Long-term + Today's Short-term + Check Yesterday's Memories)
python scripts/load_context.py --mode all

# Semantic Search (with vector retrieval)
python scripts/load_context.py --mode all --query "travel"

# Vector Search Only
python scripts/load_context.py --mode vector --query "travel"

Memory System

Long-term Memory vs Short-term Memory

Feature	Long-term Memory	Short-term Memory
Purpose	Persistent information (preferences, personal info, knowledge)	Temporary information (today's conversations, temporary to-dos)
Retention Period	Permanently saved, deleted manually	Archived after 24 hours, deleted after 30 days
Organization Method	5 files by category	Files by date ( `2026-03-11.md` )
Loading Method	Fully loaded in each conversation	Automatically loads today's file
Typical Content	"I like concise replies", "I'm a product manager"	"User is moving next week", "Physical exam in the morning"

Long-term Memory Files (5 Files)

memories/
├── user-preferences.md      # User preferences and habits
├── user-profile.md          # User personal information and background
├── decisions-context.md     # Important decisions and context
├── tasks-reminder.md        # To-do items and reminders
└── knowledge-base.md        # Knowledge and experience accumulation

Short-term Memory Files (By Date)

short-term/
├── 2026-03-11.md              # Today's short-term memory
├── 2026-03-10.md              # Yesterday's (to be archived)
└── archived/                  # Archive directory (cleaned up after 30 days)

Automatic Archiving: Automatically checks and archives files older than 24 hours every time

load_context.py --mode all

is run.

Vector Memory (Semantic Search)

Purpose: Store vectors of short-term memories to support semantic search (searching "physical exam" can also find "hospital checkup").

Note: Long-term memories are fully loaded into context and do not need to be vectorized.

bash

# Semantic Search
python scripts/load_context.py --mode all --query "travel"

# Vector Search Only
python scripts/load_context.py --mode vector --query "travel"

Memory Entry Format

markdown

## [Memory Title]

<!-- @meta category: Category | tags: Tag 1, Tag 2 | created: YYYY-MM-DD | updated: YYYY-MM-DD -->

Memory content...

### Related Memories (Optional)
- See [[Other Memory Title]](other-file.md#other-memory-title)

<!-- @end -->

Examples of Various Memories

user-preferences.md:

markdown

## Communication Style Preferences

<!-- @meta category: preferences | tags: communication style, output format | created: 2026-03-11 -->

- Reply style: Concise and direct, avoid lengthy explanations
- Output format: Prioritize tables and lists
- Language style: Professional yet friendly

<!-- @end -->

user-profile.md:

markdown

## Professional Background

<!-- @meta category: profile | tags: occupation, work | created: 2026-03-11 -->

- Occupation: Product Manager
- Industry: Internet/Technology
- Work Location: Beijing

<!-- @end -->

tasks-reminder.md:

markdown

## Child Vaccination Reminder

<!-- @meta category: tasks | tags: reminder, health | created: 2026-03-10 -->

**Reminder Item**: Take child for the third dose of DPT vaccine
**Deadline**: 2026-03-25
**Priority**: High

<!-- @end -->

Common Mistakes

Mistake	Correct Practice
❌ Skip configuration check	✅ Check configuration first after the first message
❌ Forget to load memories for the first time	✅ Run `--mode all` immediately after configuration is completed
❌ Wait until conversation ends to record	✅ Record immediately in background after identification
❌ Ask user for confirmation	✅ Record silently without interrupting conversation
❌ Tell user "I've recorded this"	✅ Continue conversation without mentioning recording
❌ Load all vector memories	✅ Must specify `--query` keyword for vector search
❌ Ignore memory management	✅ Proactively update, delete, associate, search
❌ Ask user whether to transfer	✅ AI independently assesses and transfers automatically
❌ Tell user "I've transferred memories"	✅ Transfer silently without mentioning the operation

Red Flags - STOP

About to reply to user but haven't checked configuration yet → STOP, check configuration first
About to reply to user but haven't loaded memories yet → STOP, load first
Thinking "I'll record later" → STOP, record immediately
Thinking "I'll tell the user I'm noting this" → STOP, record silently
Thinking "I'll ask confirmation 'Are you... right?'" → STOP, record directly
Thinking "I'll ask 'Do you want to transfer to long-term memory?'" → STOP, decide independently and transfer directly
Thinking "I'll tell the user 'I've transferred memories'" → STOP, stay silent

Configuration

Check Configuration Status:

bash

python scripts/check_config.py

After configuration is completed, a
configured.txt
file will be created:

Exists → Configuration completed, no further guidance will be provided
Does not exist → Configuration not completed, AI will guide configuration

Reconfigure:

bash

python scripts/check_config.py --reset
python scripts/check_config.py --guide

Verify Installation:

bash

python scripts/setup_check.py

Related Files

Core Documents:

SETUP_GUIDE.md - Complete Configuration Guide
assets/memory_template.md - Memory Entry Template

Script Files:

```
scripts/load_context.py
```
- Unified Memory Loading
```
scripts/manage_memories.py
```
- Long-term Memory Management
```
scripts/manage_short_term.py
```
- Short-term Memory Management
```
scripts/vector_store.py
```
- Vector Storage Management

Reference Documents:

```
references/linking.md
```
- Bidirectional Linking Between Memories
```
references/example_memories.md
```
- Memory Examples

Detailed Usage Instructions: references/usage.md

long-term-memory

NPX Install

Tags

SKILL.md Content (Chinese)

Long-Term Memory Management

Overview

When to Use

Quick Reference

Core Workflow

1. First Conversation - Check Configuration → Guide Configuration → Load All Memories (Mandatory)

2. During Conversation - Invisible Recording

3. Short-term Memory Expiration Assessment

4. Subsequent Conversations - Load On Demand

Memory System

Long-term Memory vs Short-term Memory

Long-term Memory Files (5 Files)

Short-term Memory Files (By Date)

Vector Memory (Semantic Search)

Memory Entry Format

Examples of Various Memories

Common Mistakes

Red Flags - STOP

Configuration

Related Files