Back to Details

memory-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Memory Search Skill

记忆搜索Skill

File-backed memory system that allows PopeBot agents to store, search, and retrieve memories across jobs. Inspired by OpenClaw's memory-core plugin.
基于文件存储的记忆系统，允许PopeBot Agent跨任务存储、搜索和检索记忆。灵感来自OpenClaw的memory-core插件。

When to Activate

激活时机

Activate this skill when:
  • You need to remember information across multiple jobs
  • You want to build a knowledge base that persists between sessions
  • You need to search past conversations or decisions
  • You're building agents that learn from experience
  • The user asks to "remember" something or "search memories"
激活本Skill的场景：
  • 当你需要跨多个任务记住信息时
  • 当你想要构建一个在会话间持久化的知识库时
  • 当你需要搜索过往对话或决策时
  • 当你构建从经验中学习的Agent时
  • 当用户要求“记住”某些内容或“搜索记忆”时

Architecture

架构

┌─────────────────────────────────────────────────────────┐
│  PopeBot Agent                                           │
│  "Remember this pattern" / "What did we learn about X?" │
└─────────────────────┬───────────────────────────────────┘
                      │ Tool calls
                      ▼
┌─────────────────────────────────────────────────────────┐
│  Memory Search Skill                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ memory_store │  │ memory_search│  │ memory_get   │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                 │                 │           │
│         └─────────────────┼─────────────────┘           │
│                           ▼                             │
│              ┌────────────────────────┐                │
│              │  File-based Index      │                │
│              │  - memories/index.json │                │
│              │  - memories/{id}.json  │                │
│              └────────────────────────┘                │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│  PopeBot Agent                                           │
│  "Remember this pattern" / "What did we learn about X?" │
└─────────────────────┬───────────────────────────────────┘
                      │ 工具调用
                      ▼
┌─────────────────────────────────────────────────────────┐
│  Memory Search Skill                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ memory_store │  │ memory_search│  │ memory_get   │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                 │                 │           │
│         └─────────────────┼─────────────────┘           │
│                           ▼                             │
│              ┌────────────────────────┐                │
│              │  基于文件的索引      │                │
│              │  - memories/index.json │                │
│              │  - memories/{id}.json  │                │
│              └────────────────────────┘                │
└─────────────────────────────────────────────────────────┘

Commands

命令

Via the 
memory
CLI or tool calls:
通过
memory
CLI或工具调用：

Store a Memory

存储记忆

bash
undefined
bash
undefined

Store with automatic tagging

自动标记存储

memory store "The user prefers TypeScript over JavaScript for new projects"
memory store "The user prefers TypeScript over JavaScript for new projects"

Store with custom tags

自定义标签存储

memory store "API rate limit is 100 requests/minute" --tags api,limits,rate-limiting
memory store "API rate limit is 100 requests/minute" --tags api,limits,rate-limiting

Store with metadata

带元数据存储

memory store "Database connection uses SSL on production" --category infrastructure --priority high
undefined
memory store "Database connection uses SSL on production" --category infrastructure --priority high
undefined

Search Memories

搜索记忆

bash
undefined
bash
undefined

Full-text search

全文搜索

memory search "TypeScript configuration"
memory search "TypeScript configuration"

Search by tag

按标签搜索

memory search --tag api
memory search --tag api

Search by category

按分类搜索

memory search --category infrastructure
memory search --category infrastructure

Combined search

组合搜索

memory search "rate limit" --tag api --limit 5
memory search "rate limit" --tag api --limit 5

Search with date range

按日期范围搜索

memory search "deployment" --after 2026-01-01 --before 2026-02-25
undefined
memory search "deployment" --after 2026-01-01 --before 2026-02-25
undefined

Get Specific Memory

获取指定记忆

bash
undefined
bash
undefined

Get by ID

按ID获取

memory get mem_abc123
memory get mem_abc123

Get recent memories

获取近期记忆

memory recent --count 10
memory recent --count 10

Get memories by tag

按标签获取记忆

memory tagged api,limits
undefined
memory tagged api,limits
undefined

List/Delete Memories

列出/删除记忆

bash
undefined
bash
undefined

List all memories

列出所有记忆

memory list
memory list

List with filters

带筛选条件列出

memory list --tag api --category infrastructure
memory list --tag api --category infrastructure

Delete a memory

删除单个记忆

memory delete mem_abc123
memory delete mem_abc123

Delete by tag

按标签删除

memory delete --tag obsolete
memory delete --tag obsolete

Clear all memories (confirmation required)

清空所有记忆（需确认）

memory clear --confirm
undefined
memory clear --confirm
undefined

Tool Calls (Agent Integration)

工具调用（Agent集成）

The skill exposes these tool calls for the Pi agent:
memory_store(content, tags, category, priority)
  - Store a new memory
  - content: string (required) - The memory content
  - tags: string[] (optional) - Tags for categorization
  - category: string (optional) - Category name
  - priority: string (optional) - 'low', 'medium', 'high' (default: 'medium')
  - Returns: { success: true, id: 'mem_abc123', timestamp: '2026-02-25T15:00:00Z' }

memory_search(query, tags, category, limit, after, before)
  - Search memories
  - query: string (optional) - Full-text search query
  - tags: string[] (optional) - Filter by tags
  - category: string (optional) - Filter by category
  - limit: number (optional) - Max results (default: 10)
  - after: string (optional) - ISO date filter
  - before: string (optional) - ISO date filter
  - Returns: { success: true, results: [{ id, content, tags, category, priority, timestamp, relevance }], total: number }

memory_get(id)
  - Get a specific memory by ID
  - id: string (required)
  - Returns: { success: true, memory: { id, content, tags, category, priority, timestamp, metadata } }

memory_recent(count)
  - Get recent memories
  - count: number (optional, default: 10)
  - Returns: { success: true, memories: [...] }

memory_delete(id)
  - Delete a memory
  - id: string (required)
  - Returns: { success: true, deleted: 'mem_abc123' }

memory_list(tags, category, limit)
  - List memories with optional filters
  - tags: string[] (optional)
  - category: string (optional)
  - limit: number (optional, default: 50)
  - Returns: { success: true, memories: [...], total: number }
本Skill为PopeBot Agent提供以下工具调用：
memory_store(content, tags, category, priority)
  - 存储新记忆
  - content: string（必填）- 记忆内容
  - tags: string[]（可选）- 分类标签
  - category: string（可选）- 分类名称
  - priority: string（可选）- 'low'、'medium'、'high'（默认：'medium'）
  - 返回: { success: true, id: 'mem_abc123', timestamp: '2026-02-25T15:00:00Z' }

memory_search(query, tags, category, limit, after, before)
  - 搜索记忆
  - query: string（可选）- 全文搜索关键词
  - tags: string[]（可选）- 按标签筛选
  - category: string（可选）- 按分类筛选
  - limit: number（可选）- 最大结果数（默认：10）
  - after: string（可选）- ISO日期筛选（晚于该日期）
  - before: string（可选）- ISO日期筛选（早于该日期）
  - 返回: { success: true, results: [{ id, content, tags, category, priority, timestamp, relevance }], total: number }

memory_get(id)
  - 按ID获取指定记忆
  - id: string（必填）
  - 返回: { success: true, memory: { id, content, tags, category, priority, timestamp, metadata } }

memory_recent(count)
  - 获取近期记忆
  - count: number（可选，默认：10）
  - 返回: { success: true, memories: [...] }

memory_delete(id)
  - 删除单个记忆
  - id: string（必填）
  - 返回: { success: true, deleted: 'mem_abc123' }

memory_list(tags, category, limit)
  - 带可选筛选条件列出记忆
  - tags: string[]（可选）
  - category: string（可选）
  - limit: number（可选，默认：50）
  - 返回: { success: true, memories: [...], total: number }

File Structure

文件结构

Memories are stored in 
.pi/memories/
:
.pi/memories/
├── index.json           # Search index (tag → memory IDs, category → memory IDs)
├── mem_abc123.json      # Individual memory files
├── mem_def456.json
└── ...
记忆存储在
.pi/memories/
目录下：
.pi/memories/
├── index.json           # 搜索索引（标签→记忆ID，分类→记忆ID）
├── mem_abc123.json      # 单个记忆文件
├── mem_def456.json
└── ...

Memory File Format

记忆文件格式

json
{
  "id": "mem_abc123",
  "content": "The user prefers TypeScript over JavaScript for new projects",
  "tags": ["preferences", "typescript", "languages"],
  "category": "user-preferences",
  "priority": "medium",
  "timestamp": "2026-02-25T15:00:00Z",
  "metadata": {
    "job_id": "job_abc123",
    "source": "agent",
    "version": 1
  }
}
json
{
  "id": "mem_abc123",
  "content": "The user prefers TypeScript over JavaScript for new projects",
  "tags": ["preferences", "typescript", "languages"],
  "category": "user-preferences",
  "priority": "medium",
  "timestamp": "2026-02-25T15:00:00Z",
  "metadata": {
    "job_id": "job_abc123",
    "source": "agent",
    "version": 1
  }
}

Index Format

索引格式

json
{
  "tags": {
    "typescript": ["mem_abc123", "mem_def456"],
    "api": ["mem_ghi789"]
  },
  "categories": {
    "user-preferences": ["mem_abc123"],
    "infrastructure": ["mem_ghi789"]
  },
  "created_at": "2026-02-25T15:00:00Z",
  "updated_at": "2026-02-25T16:30:00Z"
}
json
{
  "tags": {
    "typescript": ["mem_abc123", "mem_def456"],
    "api": ["mem_ghi789"]
  },
  "categories": {
    "user-preferences": ["mem_abc123"],
    "infrastructure": ["mem_ghi789"]
  },
  "created_at": "2026-02-25T15:00:00Z",
  "updated_at": "2026-02-25T16:30:00Z"
}

Usage Examples

使用示例

Example 1: Remember User Preferences

示例1：记住用户偏好

javascript
const memory = require('/job/.pi/skills/memory-search/memory.js');

// Store a preference
await memory.store({
  content: "User prefers concise responses with code examples",
  tags: ['preferences', 'communication-style'],
  category: 'user-preferences',
  priority: 'high'
});

// Later, retrieve preferences
const prefs = await memory.search({
  query: 'preferences',
  tags: ['communication-style']
});
javascript
const memory = require('/job/.pi/skills/memory-search/memory.js');

// 存储偏好
await memory.store({
  content: "User prefers concise responses with code examples",
  tags: ['preferences', 'communication-style'],
  category: 'user-preferences',
  priority: 'high'
});

// 后续检索偏好
const prefs = await memory.search({
  query: 'preferences',
  tags: ['communication-style']
});

Example 2: Build Project Knowledge Base

示例2：构建项目知识库

javascript
// Store discoveries during a job
await memory.store({
  content: "The API uses cursor-based pagination with 'next_cursor' field",
  tags: ['api', 'pagination', 'project-knowledge'],
  category: 'project-alpha',
  priority: 'medium'
});

await memory.store({
  content: "Database migrations are in /db/migrations, run with npm run migrate",
  tags: ['database', 'migrations', 'project-knowledge'],
  category: 'project-alpha',
  priority: 'high'
});

// Search for project knowledge
const knowledge = await memory.search({
  tags: ['project-knowledge'],
  category: 'project-alpha'
});
javascript
// 在任务执行期间存储发现的信息
await memory.store({
  content: "The API uses cursor-based pagination with 'next_cursor' field",
  tags: ['api', 'pagination', 'project-knowledge'],
  category: 'project-alpha',
  priority: 'medium'
});

await memory.store({
  content: "Database migrations are in /db/migrations, run with npm run migrate",
  tags: ['database', 'migrations', 'project-knowledge'],
  category: 'project-alpha',
  priority: 'high'
});

// 搜索项目知识库
const knowledge = await memory.search({
  tags: ['project-knowledge'],
  category: 'project-alpha'
});

Example 3: Learn from Past Mistakes

示例3：从过往错误中学习

javascript
// Store a lesson learned
await memory.store({
  content: "Do not use npm install --save, use npm install (saves by default in npm 5+)",
  tags: ['lessons-learned', 'npm', 'mistakes'],
  category: 'best-practices',
  priority: 'high'
});

// Before starting a new task, check for relevant lessons
const lessons = await memory.search({
  query: 'npm install',
  tags: ['lessons-learned']
});
javascript
// 存储学到的经验
await memory.store({
  content: "Do not use npm install --save, use npm install (saves by default in npm 5+)",
  tags: ['lessons-learned', 'npm', 'mistakes'],
  category: 'best-practices',
  priority: 'high'
});

// 开始新任务前，检查相关经验
const lessons = await memory.search({
  query: 'npm install',
  tags: ['lessons-learned']
});

Example 4: Cross-Job Context

示例4：跨任务上下文

javascript
// Job 1: Research phase
await memory.store({
  content: "Competitor analysis: Company X uses React, Company Y uses Vue",
  tags: ['research', 'competitive-analysis'],
  category: 'market-research',
  priority: 'medium'
});

// Job 2: Implementation phase (different job, same memory)
const research = await memory.search({
  tags: ['competitive-analysis'],
  category: 'market-research'
});
// Now the implementation agent knows the competitive landscape
javascript
// 任务1：调研阶段
await memory.store({
  content: "Competitor analysis: Company X uses React, Company Y uses Vue",
  tags: ['research', 'competitive-analysis'],
  category: 'market-research',
  priority: 'medium'
});

// 任务2：实现阶段（不同任务，共享同一记忆）
const research = await memory.search({
  tags: ['competitive-analysis'],
  category: 'market-research'
});
// 此时实现Agent已了解竞争格局

Configuration

配置

Create 
.pi/memories/config.json
(optional):
json
{
  "maxMemories": 10000,
  "autoTag": true,
  "defaultCategory": "general",
  "defaultPriority": "medium",
  "searchRelevance": {
    "tagMatch": 3,
    "categoryMatch": 2,
    "contentMatch": 1
  },
  "retention": {
    "enabled": false,
    "deleteAfterDays": 90,
    "archiveAfterDays": 30
  }
}
创建
.pi/memories/config.json
（可选）：
json
{
  "maxMemories": 10000,
  "autoTag": true,
  "defaultCategory": "general",
  "defaultPriority": "medium",
  "searchRelevance": {
    "tagMatch": 3,
    "categoryMatch": 2,
    "contentMatch": 1
  },
  "retention": {
    "enabled": false,
    "deleteAfterDays": 90,
    "archiveAfterDays": 30
  }
}

Search Algorithm

搜索算法

The search uses a simple relevance scoring system:
  1. Tag match: +3 points per matching tag
  2. Category match: +2 points if category matches
  3. Content match: +1 point per matching word in content
  4. Priority boost: high=+2, medium=+1, low=+0
  5. Recency bonus: +0.1 points per day within last 7 days
Results are sorted by relevance score (descending).
搜索使用简单的相关性评分系统：
  1. 标签匹配：每个匹配标签加3分
  2. 分类匹配：分类匹配加2分
  3. 内容匹配：内容中每个匹配词加1分
  4. 优先级加成：高优先级+2分，中优先级+1分，低优先级+0分
  5. 近期奖励：过去7天内，每天加0.1分
结果按相关性得分降序排列。

Installation

安装

bash
undefined
bash
undefined

Activate the skill

激活Skill

cd /job/.pi/skills ln -s ../../pi-skills/memory-search memory-search
cd /job/.pi/skills ln -s ../../pi-skills/memory-search memory-search

Install dependencies

安装依赖

cd memory-search npm install
undefined
cd memory-search npm install
undefined

Dependencies

依赖项

json
{
  "natural": "^6.0.4",
  "node-fetch": "^3.3.2"
}
json
{
  "natural": "^6.0.4",
  "node-fetch": "^3.3.2"
}

Testing

测试

bash
undefined
bash
undefined

Run test suite

运行测试套件

node /job/.pi/skills/memory-search/test.js
node /job/.pi/skills/memory-search/test.js

Run integration test

运行集成测试

node /job/.pi/skills/memory-search/test.js --integration
undefined
node /job/.pi/skills/memory-search/test.js --integration
undefined

When to Use

适用场景

  • Building agents that need long-term memory
  • Projects spanning multiple jobs
  • Learning from past mistakes and successes
  • Storing user preferences
  • Building knowledge bases
  • Cross-session context sharing
  • 构建需要长期记忆的Agent
  • 跨多个任务的项目
  • 从过往错误和成功中学习
  • 存储用户偏好
  • 构建知识库
  • 跨会话上下文共享

When NOT to Use

不适用场景

  • Single-job tasks with no future relevance
  • Storing sensitive credentials (use GitHub Secrets)
  • Large binary data (use file storage instead)
  • Real-time data that changes frequently
  • 无未来关联的单任务
  • 存储敏感凭证（请使用GitHub Secrets）
  • 大型二进制数据（请使用文件存储）
  • 频繁变化的实时数据

Security Considerations

安全注意事项

  • Memories are stored in plaintext files (not encrypted)
  • Do not store passwords, API keys, or sensitive data
  • Memory files are included in git by default (can be gitignored)
  • Consider adding 
    .pi/memories/
    to 
    .gitignore
    for sensitive projects
  • 记忆以明文文件存储（未加密）
  • 请勿存储密码、API密钥或敏感数据
  • 记忆文件默认会被Git追踪（可添加到.gitignore）
  • 对于敏感项目，建议将
    .pi/memories/
    添加到
    .gitignore

Troubleshooting

故障排除

IssueSolution
Memory not foundCheck memory ID format (mem_xxxxxx)
Search returns no resultsTry broader query or check tag spelling
Index out of syncRun 
memory rebuild-index
Memory file corruptedCheck JSON syntax in memory file
问题解决方案
记忆未找到检查记忆ID格式（应为mem_xxxxxx）
搜索无结果尝试更宽泛的关键词或检查标签拼写
索引不同步运行
memory rebuild-index
记忆文件损坏检查记忆文件中的JSON语法

Future Enhancements

未来增强计划

  • Vector search with embeddings
  • Memory compression/archiving
  • Cross-agent memory sharing
  • Memory expiration
  • Memory versioning
  • SQLite backend option
  • 基于向量嵌入的向量搜索
  • 记忆压缩/归档
  • 跨Agent记忆共享
  • 记忆过期机制
  • 记忆版本控制
  • SQLite后端选项

Credits

致谢

Inspired by OpenClaw's memory-core plugin. Reimplemented for PopeBot with enhanced search and CLI interface.
灵感来自OpenClaw的memory-core插件。针对PopeBot重新实现，增强了搜索功能和CLI界面。