dominds 1.4.2 → 1.5.1

package/dist/tools/prompts/memory/en/scenarios.md

@@ -0,0 +1,174 @@
+# memory Usage Scenarios
+
+## Template (Scenarios)
+
+### Scenario Format
+
+- Goal
+- Preconditions
+- Steps
+- Expected Signal
+- Failure Branch
+- Completion Criteria
+
+## Scenario 1: Task Progress Tracking
+
+### Scenario Description
+
+In long-running tasks, you need to persist task progress to continue after restart.
+
+### Example
+
+**Add Task List**
+
+```typescript
+add_memory({
+  path: 'project/i18n-tasks',
+  content:
+    '## TODO\n\n- [ ] Create ws_mod manual\n- [ ] Create team_mgmt manual\n- [ ] Create memory manual\n- [ ] Create control manual\n\n## In Progress\n- [ ] Create ws_mod manual [100%]',
+});
+```
+
+**Update Task Progress**
+
+```typescript
+replace_memory({
+  path: 'project/i18n-tasks',
+  content:
+    '## TODO\n\n- [ ] Create team_mgmt manual\n- [ ] Create memory manual\n- [ ] Create control manual\n\n## Completed\n- [x] Create ws_mod manual\n\n## In Progress\n- [ ] Create team_mgmt manual [50%]',
+});
+```
+
+## Scenario 2: User Preferences Storage
+
+### Scenario Description
+
+Save user preferences, such as programming language, theme, etc.
+
+### Example
+
+**Save User Preferences**
+
+```typescript
+add_memory({
+  path: 'user/preferences',
+  content:
+    '## User Preferences\n\n- Programming Language: TypeScript\n- Code Style: strict\n- Theme: dark\n- Auto Save: true',
+});
+```
+
+**Update Preferences**
+
+```typescript
+replace_memory({
+  path: 'user/preferences',
+  content:
+    '## User Preferences\n\n- Programming Language: TypeScript\n- Code Style: strict\n- Theme: light\n- Auto Save: true',
+});
+```
+
+## Scenario 3: Context Information Preservation
+
+### Scenario Description
+
+In complex tasks, save important context information to avoid repeated queries.
+
+### Example
+
+**Save API Information**
+
+```typescript
+add_memory({
+  path: 'context/api-endpoints',
+  content:
+    '## API Endpoints\n\n- User Login: POST /api/auth/login\n- Get User Info: GET /api/user/info\n- Update User Settings: PUT /api/user/settings\n\n## Authentication\n- Use Bearer Token\n- Validity: 24 hours',
+});
+```
+
+**Save Tech Stack**
+
+```typescript
+add_memory({
+  path: 'context/tech-stack',
+  content:
+    '## Tech Stack\n\n- Frontend: React + TypeScript\n- Backend: Node.js + Express\n- Database: PostgreSQL\n- Cache: Redis',
+});
+```
+
+## Scenario 4: Meeting Notes
+
+### Scenario Description
+
+Save meeting highlights and decisions.
+
+### Example
+
+```typescript
+add_memory({
+  path: 'meeting/2024-01-15',
+  content:
+    '## Meeting Notes: 2024-01-15\n\n### Participants\n- @fullstack\n- @i18n\n- @ux\n\n### Agenda\n1. i18n manual creation plan\n2. man function UX improvements\n\n### Decisions\n- Prioritize creating ws_mod and team_mgmt manuals\n- man function supports fuzzy matching\n\n### TODO\n- @i18n: Create memory manual\n- @fullstack: Optimize man function',
+});
+```
+
+## Scenario 5: Knowledge Base
+
+### Scenario Description
+
+Build a personal knowledge base and save learning notes.
+
+### Example
+
+```typescript
+add_memory({
+  path: 'knowledge/typescript-tips',
+  content:
+    '## TypeScript Tips\n\n### 1. Type Inference\nconst x = 1; // Type inferred as number\n\n### 2. Interface vs Type\n- Interface: Extensible, suitable for object types\n- Type: Supports union types, intersection types\n\n### 3. Strict Mode\nEnabling strict mode provides better type safety',
+});
+```
+
+## Scenario 6: Temporary Notes
+
+### Scenario Description
+
+Temporarily save information to process later.
+
+### Example
+
+```typescript
+add_memory({
+  path: 'scratchpad/temp-notes',
+  content:
+    '## Temporary Notes\n\n- TODO: Check team.yaml configuration\n- TODO: Verify man function types\n- TODO: Update taskdoc progress',
+});
+```
+
+**Delete after processing**
+
+```typescript
+drop_memory({
+  path: 'scratchpad/temp-notes',
+});
+```
+
+## Scenario 7: Cleaning Up Outdated Memory
+
+### Scenario Description
+
+Regularly clean up memories that are no longer needed.
+
+### Example
+
+```typescript
+// View all current memories (agent can read)
+// Delete unnecessary memories one by one
+drop_memory({
+  path: 'project/old-feature',
+});
+```
+
+Or use `clear_memory` to clear all memories (use with caution):
+
+```typescript
+clear_memory({});
+```

package/dist/tools/prompts/memory/en/tools.md

@@ -0,0 +1,154 @@
+# memory Tool Reference
+
+## Template (Tools)
+
+### How to Read
+
+- The schema-generated "Tool Contract (Schema)" section is canonical for parameters/returns.
+
+### Per-Tool Fields (order)
+
+1. Purpose
+2. Call Signature
+3. Parameters (refer to schema)
+4. Preconditions
+5. Success Signal
+6. Failure/Errors
+7. Copy-Ready Example
+8. Common Misuse
+
+## Tool List
+
+### 1. add_memory
+
+Create new memory (when path does not exist).
+
+**Parameters:**
+
+- `path` (required): Unique identifier for the memory
+- `content` (required): Memory content
+
+**Returns:**
+
+```yaml
+status: ok|error
+path: <memory path>
+content_size: <content size in bytes>
+created_at: <creation timestamp>
+```
+
+**Errors:**
+
+- `MEMORY_ALREADY_EXISTS`: Path already exists, use `replace_memory` to update
+
+### 2. replace_memory
+
+Update existing memory (when path exists).
+
+**Parameters:**
+
+- `path` (required): Unique identifier for the memory
+- `content` (required): New memory content
+
+**Returns:**
+
+```yaml
+status: ok|error
+path: <memory path>
+content_size: <content size in bytes>
+updated_at: <update timestamp>
+```
+
+**Errors:**
+
+- `MEMORY_NOT_FOUND`: Path does not exist, use `add_memory` to create
+
+### 3. drop_memory
+
+Delete specified memory.
+
+**Parameters:**
+
+- `path` (required): Memory path to delete
+
+**Returns:**
+
+```yaml
+status: ok|error
+path: <memory path>
+deleted_at: <deletion timestamp>
+```
+
+**Errors:**
+
+- `MEMORY_NOT_FOUND`: Path does not exist
+
+### 4. clear_memory
+
+Clear all personal memory.
+
+**Warning:** This operation is irreversible!
+
+**Parameters:** None
+
+**Returns:**
+
+```yaml
+status: ok|error
+cleared_count: <number of memories deleted>
+cleared_at: <deletion timestamp>
+```
+
+**Errors:**
+
+- None (returns success even if no memories exist)
+
+## Usage Examples
+
+### Add New Memory
+
+```typescript
+add_memory({
+  path: 'project/todo',
+  content: '- Complete i18n docs\n- Write test cases\n- Update README',
+});
+```
+
+### Update Existing Memory
+
+```typescript
+replace_memory({
+  path: 'project/todo',
+  content: '- Complete i18n docs [DONE]\n- Write test cases [IN PROGRESS]\n- Update README',
+});
+```
+
+### Delete Memory
+
+```typescript
+drop_memory({
+  path: 'project/todo',
+});
+```
+
+### Clear All Memory
+
+```typescript
+clear_memory({});
+```
+
+## YAML Output Contract
+
+All tool outputs use YAML format for programmatic processing:
+
+- `status`: Operation status, `ok` for success, `error` for failure
+- `path`: Memory path
+- Other fields: Additional information for specific operations
+
+On error, returns:
+
+```yaml
+status: error
+error_code: <error code>
+message: <error message>
+```

package/dist/tools/prompts/memory/zh/errors.md

@@ -0,0 +1,155 @@
+# memory 错误处理
+
+## 模板（错误）
+
+### 错误行动链（必填）
+
+1. 触发条件
+2. 检测信号
+3. 恢复步骤
+4. 成功判据
+5. 升级路径（可选）
+
+## 错误代码
+
+### MEMORY_ALREADY_EXISTS
+
+**描述：** 路径已存在，无法使用 `add_memory` 创建新记忆。
+
+**原因：**
+
+- 尝试添加的路径已经被其他记忆占用
+
+**解决方案：**
+
+- 使用 `replace_memory` 更新已有记忆
+- 或者使用不同的路径创建新记忆
+
+**示例：**
+
+```
+错误：
+status: error
+error_code: MEMORY_ALREADY_EXISTS
+message: 路径 "project/todo" 已存在，请使用 replace_memory 更新
+```
+
+### MEMORY_NOT_FOUND
+
+**描述：** 路径不存在，无法执行操作。
+
+**原因：**
+
+- 尝试访问的记忆路径不存在
+- 路径被删除或从未创建
+
+**解决方案：**
+
+- 如果是更新/删除操作，先使用 `add_memory` 创建
+- 检查路径是否正确
+
+**示例：**
+
+```
+错误：
+status: error
+error_code: MEMORY_NOT_FOUND
+message: 路径 "project/todo" 不存在，请先使用 add_memory 创建
+```
+
+### MEMORY_PATH_INVALID
+
+**描述：** 路径格式无效。
+
+**原因：**
+
+- 路径包含非法字符
+- 路径长度超过限制
+
+**解决方案：**
+
+- 确保路径只包含字母、数字、下划线、斜杠
+- 路径长度不超过 255 个字符
+
+**示例：**
+
+```
+错误：
+status: error
+error_code: MEMORY_PATH_INVALID
+message: 路径 "project/*invalid*" 包含非法字符
+```
+
+### MEMORY_CONTENT_TOO_LARGE
+
+**描述：** 记忆内容过大。
+
+**原因：**
+
+- 单条记忆内容超过 1MB 限制
+
+**解决方案：**
+
+- 压缩内容
+- 拆分为多条记忆
+- 使用外部存储（如文件）
+
+**示例：**
+
+```
+错误：
+status: error
+error_code: MEMORY_CONTENT_TOO_LARGE
+message: 内容大小 1.2MB 超过 1MB 限制
+```
+
+### MEMORY_STORAGE_ERROR
+
+**描述：** 存储错误。
+
+**原因：**
+
+- 磁盘空间不足
+- 权限问题
+- 文件系统错误
+
+**解决方案：**
+
+- 检查磁盘空间
+- 检查文件权限
+- 重试操作
+
+**示例：**
+
+```
+错误：
+status: error
+error_code: MEMORY_STORAGE_ERROR
+message: 无法写入存储，磁盘空间不足
+```
+
+## 常见问题
+
+### Q: 记忆会自动保存吗？
+
+A: 是的，所有记忆操作都会立即持久化到磁盘。不需要手动保存。
+
+### Q: 记忆有数量限制吗？
+
+A: 没有严格的数量限制，但建议保持记忆数量在合理范围内（建议少于 100 条）。
+
+### Q: 记忆可以被其他成员看到吗？
+
+A: 不可以，memory 是个人记忆工具，只有当前智能体可以访问。如果需要共享给团队成员，请使用 team_memory。
+
+### Q: clear_memory 会删除所有记忆吗？
+
+A: 是的，`clear_memory` 会删除所有个人记忆，此操作不可恢复。请谨慎使用。
+
+### Q: 记忆会过期吗？
+
+A: 不会，记忆会永久保存，直到被显式删除。
+
+### Q: 如何查看当前所有记忆？
+
+A: 智能体在生成回复时可以访问所有个人记忆。你可以直接询问智能体当前有哪些记忆。

package/dist/tools/prompts/memory/zh/index.md

@@ -0,0 +1,47 @@
+# memory 个人记忆工具手册
+
+## 模板（概述）
+
+### 一句话定位
+
+- <该工具集用途，一句话描述>
+
+### 工具清单
+
+- <列出核心工具，或指向 Tools/Schema 章节>
+
+### 30 秒上手
+
+1. <调用 ...>
+2. <观察 ...>
+3. <下一步 ...>
+
+### 导航
+
+- principles / tools / scenarios / errors
+
+### 与其他工具集的边界
+
+- <何时用本工具集、何时用相邻工具集>
+
+memory 是 Dominds 的**个人记忆工具集**，用于管理智能体的私有记忆：
+
+- **私有性**：记忆仅对当前智能体可见，不会共享给其他成员
+- **持久化**：记忆会持久化到磁盘，在对话重启后仍然保留
+- **结构化**：支持按路径组织记忆，便于分类和检索
+
+## 快速导航
+
+| 主题                          | 描述                             |
+| ----------------------------- | -------------------------------- |
+| [principles](./principles.md) | 核心概念、记忆生命周期、最佳实践 |
+| [tools](./tools.md)           | 完整工具列表与接口契约           |
+| [scenarios](./scenarios.md)   | 常见使用场景与示例（复制即用）   |
+| [errors](./errors.md)         | 错误代码与解决方案               |
+
+## 状态
+
+- 状态：已实现
+- 主要实现文件：
+  - 工具实现：`dominds/main/tools/mem.ts`
+  - toolset 元信息：`dominds/main/tools/builtins.ts`、`dominds/main/tools/registry.ts`

package/dist/tools/prompts/memory/zh/principles.md

@@ -0,0 +1,79 @@
+# memory 原则与核心概念
+
+## 模板（原则）
+
+### 设计目标
+
+- <目标 1>
+- <目标 2>
+
+### 契约原则
+
+- <输入/输出契约规则>
+
+### 安全与边界
+
+- <访问约束/护栏>
+
+### 失败与恢复
+
+- <调用失败时的行动>
+
+### 术语表
+
+- <该工具集特有术语>
+
+## 记忆模型
+
+memory 工具集采用**路径键值存储**模型：
+
+- **路径（path）**：记忆的唯一标识符，类似于文件系统路径，例如 `project/todo` 或 `user/preferences/theme`
+- **内容（content）**：记忆的实际内容，可以是任意文本
+
+## 工具概览
+
+| 工具           | 功能                         |
+| -------------- | ---------------------------- |
+| add_memory     | 创建新记忆（路径不存在时）   |
+| replace_memory | 更新已有记忆（路径存在时）   |
+| drop_memory    | 删除记忆                     |
+| clear_memory   | 清空所有个人记忆（不可恢复） |
+
+## 记忆生命周期
+
+1. **创建（add）**：使用 `add_memory` 创建新记忆
+2. **读取（read）**：智能体在生成回复时可读取已有记忆
+3. **更新（replace）**：使用 `replace_memory` 更新记忆内容
+4. **删除（drop）**：使用 `drop_memory` 删除特定记忆
+
+## 最佳实践
+
+### 1. 路径命名规范
+
+- 使用描述性路径：`project/architecture`、`user/preferences/language`
+- 避免使用特殊字符：路径中不要包含 `/`、`\`、`*` 等
+- 使用层级结构：按主题组织记忆，例如 `project/todo`、`project/done`
+
+### 2. 内容格式
+
+- 保持内容简洁：每条记忆只包含一个主题
+- 使用结构化格式：可以使用 Markdown 格式组织内容
+- 定期清理：定期检查并删除过时的记忆
+
+### 3. 使用场景
+
+- **任务持久化**：保存长期任务进度
+- **上下文记忆**：保存对话上下文中的重要信息
+- **偏好设置**：保存用户偏好和配置信息
+
+## 与其他工具的关系
+
+- **team_memory**：团队共享记忆，所有成员可见
+- **reminder**：临时提醒，会话级别
+- **change_mind**：更新差遣牒（goals/constraints/progress）
+
+## 限制与注意事项
+
+1. 记忆内容有大小限制（单条记忆最大 1MB）
+2. 记忆路径不能超过 255 个字符
+3. `clear_memory` 会删除所有记忆，**不可恢复**