SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslong-term-memory

long-term-memory

General & other

View repository

Updated 10-16 07:23

About this skill

Long-term Memory Management

Overview

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

Core Principles：

  • The first conversation must first check the configuration status → guide configuration → load all memories
  • At all times during the conversation, identify recordable information
  • Proactively manage memories (update, delete, associate, search)

When to Use

Use this skill when：

  • The user mentions personal information (occupation, location, family situation)
  • The user expresses preferences (communication style, output format)
  • The user makes important decisions or commitments
  • The user mentions to-dos or reminders
  • The user shares knowledge, experience, or business rules
  • Context continuity across sessions is needed

Do not use：

  • One-off conversations that require no follow-up
  • Purely technical questions with no personalization needs

Quick Reference

Task Command
Check configuration python scripts/check_config.py
Write configuration directly 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 "关键词"
Add long-term memory python scripts/manage_memories.py add --file <文件> --title "标题" --content "内容"
Search long-term memory python scripts/manage_memories.py search --query "关键词"
Update long-term memory python scripts/manage_memories.py update --file <文件> --title "标题" --content "新内容"
Delete long-term memory python scripts/manage_memories.py delete --file <文件> --title "标题"
Add short-term memory python scripts/manage_short_term.py add --content "内容" --agent chat
View today's memories python scripts/manage_short_term.py show
Vector search python scripts/vector_store.py query --query "关键词" --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：

检测用户第一条消息
    ↓
检查配置状态（必须！）
    ├─ 未配置 → 引导用户配置 → 配置完成后加载记忆
    └─ 已配置 → 直接加载全部记忆

Step 1: Check configuration status

python scripts/check_config.py

Configuration status determination：

  • ✅ Exists configured.txt → Configuration is complete
  • ❌ Does not exist configured.txt → Configuration is incomplete, the user must be guided

Step 2: Write configuration directly (if incomplete)

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)

Explain to the user during guidance：

"I noticed that the memory system has not been configured yet. Please provide your OpenAI API Key, and I will help you complete the configuration."

After obtaining the API Key, write it directly：

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

Step 3: Load all memories (after configuration is complete)

python scripts/load_context.py --mode all

Complete loading process：

  1. Detect the user's first message
  2. First check the configuration status
  3. If not configured → guide configuration
  4. Run the load command
  5. Automatically archive expired short-term memories (>24 hours)
  6. Load long-term memories + the day's short-term memories
  7. Summarize the key points of the memories
  8. Adjust the interaction style based on the memories
  9. Start replying

Inner monologue example：

"The user's first message; check the configuration first. Configuration is complete; now load memories. Loading complete: 13 long-term memories and 2 short-term memories from today. The user is a product manager, works in Beijing, and prefers concise replies. Okay, now I can start replying."

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

2. During the conversation - Seamless recording

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

Use Cases：

  • Long-term Memory: User preferences, personal information, important decisions, knowledge and experience → Use manage_memories.py
  • Short-term Memory: Temporary information of the day, follow-up items, messages between Agents → Use manage_short_term.py
用户输入 → 识别可记录信息 → 后台记录 → 继续正常对话

Recognition Patterns：

Information Type User Expression Example Record To Memory Type
Personal Information "I am a product manager", "I am in Beijing" user-profile.md Long-term
Preference Statement "I like concise replies", "Use a table" user-preferences.md Long-term
Important Decision "I decided to choose A", "Execute next week" decisions-context.md Long-term
To-do Item "Remember to remind me", "Complete before Wednesday" tasks-reminder.md Long-term
Knowledge and Experience "This process is...", "Note..." knowledge-base.md Long-term
Temporary Information "Moving next week", "Have a physical examination in the morning" Short-term memory file Short-term
Agent Message "Tell the health assistant that the user needs a physical examination" Short-term memory file Short-term

Correct Approach：

用户：我是做产品经理的，平时工作比较忙
      ↓
AI：（后台运行 manage_memories.py add --file user-profile.md ...）
    那您平时喜欢怎么放松呢？

Incorrect Approach：

❌ AI：我记一下，您是产品经理对吗？好的已记录...
   （打断对话，破坏体验）

Do not ask for confirmation! Do not tell the user you are recording! Record silently, continue the conversation!

3. Short-term Memory Expiration Assessment

Timing: Each time memory is loaded, check yesterday's short-term memory (about to be archived)

Core Principles: AI evaluates independently, decides independently, no need to ask the user

Assessment Process：

检查昨天短期记忆 → AI 自主识别有价值内容 → 自动转入长期记忆 → 继续对话

Assessment Criteria(If any is met, it should be transferred to long-term):

  • ✅ User preferences or habits (e.g., "I like concise replies")
  • ✅ Important personal information (e.g., "preparing for the PMP certification", "moving to a new address")
  • ✅ Long-term to-dos or commitments (e.g., "work out 3 times a week")
  • ✅ Important knowledge or experience (e.g., "key steps in the workflow")
  • ❌ Temporary information (completed, one-time) → Let it be archived naturally

Example：

用户：（昨天说过）我准备考 PMP 证书，已经报名了
      ↓
AI：（后台检查短期记忆，识别为重要个人发展计划）
    （自动运行 manage_memories.py add --file tasks-reminder.md ...）
    （继续正常对话，不提及转移操作）

Completely unnoticeable! Do not ask! Do not tell the user! AI decides independently, transfers automatically!

4. Subsequent Conversations - Load on Demand

# 默认模式（长期 + 当天短期 + 检查昨天记忆）
python scripts/load_context.py --mode all

# 语义搜索（附加向量检索）
python scripts/load_context.py --mode all --query "旅行"

# 仅向量搜索
python scripts/load_context.py --mode vector --query "旅行"

Memory System

Long-term Memory vs Short-term Memory

Feature Long-term Memory Short-term Memory
Purpose Persistent information (preferences, personal information, knowledge) Temporary information (conversations of the day, temporary to-dos)
Retention Time Permanently saved, manually deleted Archived after 24 hours, deleted after 30 days
Organization Method Divided into 5 files by category Files divided by date (2026-03-11.md）
Loading Method Fully loaded for each conversation Automatically load the current day's file
Typical Content "I like concise replies", "I am a product manager" "The user said they are moving next week", "There is a medical checkup in the morning"

Long-term memory files (5)

memories/
├── user-preferences.md      # 用户偏好和习惯
├── user-profile.md          # 用户个人信息和背景
├── decisions-context.md     # 重要决定和上下文
├── tasks-reminder.md        # 待办事项和提醒
└── knowledge-base.md        # 知识和经验积累

Short-term memory files (by date)

short-term/
├── 2026-03-11.md              # 今天的短期记忆
├── 2026-03-10.md              # 昨天的（待归档）
└── archived/                  # 归档目录（30 天后清理）

Auto-archive: automatically checks and archives files older than 24 hours on each run of load_context.py --mode all .

Vector memory (semantic search)

Purpose: stores vectors of short-term memories, supports semantic search (searching "medical checkup" can also find "hospital examination").

Note: long-term memories are already fully loaded into context and do not need vectorization.

# 语义搜索
python scripts/load_context.py --mode all --query "旅行"

# 仅向量搜索
python scripts/load_context.py --mode vector --query "旅行"

Memory entry format

## [记忆标题]

<!-- @meta category: 类别 | tags: 标签 1, 标签 2 | created: YYYY-MM-DD | updated: YYYY-MM-DD -->

记忆内容...

### 相关记忆（可选）
- 参见 [[其他记忆标题]](其他文件.md#其他记忆标题)

<!-- @end -->

Examples of various memories

user-preferences.md：

## 沟通风格偏好

<!-- @meta category: preferences | tags: 沟通风格，输出格式 | created: 2026-03-11 -->

- 回复风格：简洁直接，避免冗长解释
- 输出格式：优先使用表格和列表
- 语言风格：专业但友好

<!-- @end -->

user-profile.md：

## 职业背景

<!-- @meta category: profile | tags: 职业，工作 | created: 2026-03-11 -->

- 职业：产品经理
- 行业：互联网/科技
- 工作地点：北京

<!-- @end -->

tasks-reminder.md：

## 孩子疫苗接种提醒

<!-- @meta category: tasks | tags: 提醒，健康 | created: 2026-03-10 -->

**提醒事项**：带孩子接种百白破疫苗第三针
**截止日期**：2026-03-25
**优先级**：高

<!-- @end -->

Common Mistakes

Wrong Correct approach
❌ Skip configuration check ✅ Check configuration first after the first message
❌ Forget to load memories for the first time ✅ Run immediately after configuration is complete --mode all
❌ Wait until the conversation ends to record ✅ Record in the background immediately after recognition
❌ Ask the user for confirmation ✅ Record silently without interrupting the conversation
❌ Tell the user "I have recorded it" ✅ Continue the conversation without mentioning the record
❌ Load all vector memories ✅ Vector search must specify --query keywords
❌ Ignore memory management ✅ Proactively update, delete, associate, and search
❌ Ask the user whether to transfer ✅ AI evaluates autonomously and transfers automatically
❌ Tell the user "I am dumping memories" ✅ Transfer silently without mentioning the operation

Red Flags - STOP

  • About to reply to the user but have not checked configuration yet → STOP, check configuration first
  • About to reply to the user but have not loaded memories yet → STOP, load first
  • Thinking "I'll record it later" → STOP, record immediately
  • Wanting to tell the user "let me note this down" → STOP, record silently
  • Wanting to ask for confirmation "You are... right?" → STOP, record directly
  • Wanting to ask "Should this be transferred to long-term memory?" → STOP, decide autonomously and transfer directly
  • Wanting to tell the user "I have transferred the memory" → STOP, remain silent

Configuration

Check configuration status：

python scripts/check_config.py

Created after configuration is complete configured.txt file：

  • Exists → configuration complete, will not guide again
  • Does not exist → configuration incomplete, AI will guide configuration

Reconfigure：

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

Verify installation：

python scripts/setup_check.py

Related Files

Core documentation：

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 documentation：

  • references/linking.md - Bidirectional links between memories
  • references/example_memories.md - Memory examples

Detailed usage instructions:references/usage.md