@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/plugins/cteno.memory/tools/memory/TOOL.md

@@ -0,0 +1,492 @@
+---
+id: "memory"
+name: "Persistent Memory"
+description: "Save, recall, and consolidate persistent knowledge across sessions. Supports fast daily logs and slow LLM dreaming into durable topic memories."
+category: "system"
+version: "3.1.0"
+supports_background: false
+# Fully externalized plugin tool: BOTH the declaration (this file) and the
+# execution body (the bundled `cteno-wiki` CLI) ship inside the cteno.memory
+# plugin. The host only spawns the declared command and pipes tool input JSON
+# on stdin — it holds no memory business logic at all.
+# Contract: exit code decides success; stdout carries the agent-facing result.
+# See docs/architecture/cteno-wiki-memory-plugin.md.
+handler:
+  type: command
+  command: cteno-wiki
+  args: ["tool"]
+  timeout_secs: 180
+input_schema:
+  type: object
+  description: "Persistent memory operations. Choose an action and provide the required fields for that action."
+  oneOf:
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "save"
+          description: "Save a durable fact into an OKF topic page and upsert its index.md entry. Repeated exact saves are de-duplicated."
+        file_path:
+          type: string
+          description: "Scope-relative OKF topic path, e.g. 'USER.md', 'knowledge/rust.md', or 'incidents/build.md'. Legacy MEMORY.md callers are redirected to knowledge/general.md."
+        content:
+          type: string
+          description: "Durable Markdown fact or section to merge into the topic page. Do not include daily/transient logs."
+        type:
+          type: string
+          enum: ["user", "feedback", "project", "reference", "incident", "workflow"]
+          description: "记忆类型标签。user=用户偏好/习惯, feedback=经验教训/规则, project=项目架构/约定, reference=领域知识/参考, incident=事故/复盘, workflow=工作流/协作规则"
+        scope:
+          type: string
+          enum: ["private", "global"]
+          description: "Memory scope. 'private' (default) saves to your persona's private space. 'global' saves to shared workspace visible to all personas."
+      required: ["action", "content", "type"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "overwrite"
+          description: "Replace a memory page with newly authored OKF content, unioning its sources[] provenance with the existing page (read-modify-write). The merge primitive for wiki consolidation."
+        file_path:
+          type: string
+          description: "Workspace-relative page path, e.g. 'knowledge/rust.md'."
+        content:
+          type: string
+          description: "Full OKF page content (YAML frontmatter + markdown body)."
+        sources:
+          type: array
+          items:
+            type: string
+          description: "Provenance strings to record (e.g. 'log: logs/2026/06/2026-06-20.md'); unioned with the page's existing sources[]."
+        scope:
+          type: string
+          enum: ["private", "global"]
+      required: ["action", "file_path", "content"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "recall"
+          description: "Wiki recall across BOTH private and global memory: index-first whole pages under a Unicode-character budget (not keyword chunks). Oversized bodies are represented by path for existing grep + ranged read. Only a total miss returns the topic index map."
+        query:
+          type: string
+          description: "Topic query — matched against the topic-organized index (topic, title, path, description)."
+        type:
+          type: string
+          enum: ["user", "feedback", "project", "reference", "incident", "workflow"]
+          description: "可选类型过滤。设置后只返回匹配类型的记忆。"
+        limit:
+          type: integer
+          description: "Maximum pages to return (default 10)."
+        max_chars:
+          type: integer
+          minimum: 1
+          description: "Maximum total Unicode characters of whole-page bodies to include (default 32000). Oversized pages are returned as path descriptors for grep + ranged read; no page is silently cut."
+        project:
+          type: string
+          description: "Optional absolute path of ANOTHER project root to drill into READ-ONLY (its <project>/.cteno/memory only; no global). Use it from the main conversation to look into a project listed in <project_directory>. Only recall/read/list read through it; log appends a forwarded entry to its daily log; save/overwrite/delete/dream reject it."
+      required: ["action", "query"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "sync_docs"
+          description: "Reconcile the active project's docs/**/*.md(x) files byte-for-byte into managed raw/docs/** OKF pages. Creates, updates, and removes pages by source fingerprint."
+        scope:
+          type: string
+          const: "private"
+          description: "Project docs always sync into the active project's private memory scope."
+      required: ["action"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "log"
+          description: "Append a timestamped fast-memory entry to today's daily log. With `project`, forward it append-only to that project's daily log as well."
+        content:
+          type: string
+          description: "Concise event/fact to append. This is append-only source material, not polished long-term memory."
+        source:
+          type: string
+          description: "Optional source label, e.g. session, slack, figma, gate, traffic."
+        scope:
+          type: string
+          enum: ["private", "global"]
+          description: "Where to store the daily log. 'private' (default) uses the current project/persona memory; 'global' uses shared memory."
+        project:
+          type: string
+          description: "Optional absolute root of a known project (listed in <project_directory>). Forwards this entry APPEND-ONLY into <project>/.cteno/memory/logs/<today>.md with an origin note (which Jelly/session, when), and keeps a marked copy in your own log. The project's own dream consolidates it. Use it from a main conversation for project decisions; never writes project pages."
+        origin_entry:
+          type: string
+          description: "Dream routing only (with project): the source log entry being forwarded, as '<log path> <HH:MM:SS>', e.g. 'logs/2026/10/2026-10-27.md 18:35:06'. Makes the forward idempotent; no copy is written to your own log."
+      required: ["action", "content"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "dream"
+          description: "Run slow-memory LLM consolidation: read daily logs and the topic index, then merge durable facts into OKF wiki pages (index.md entries are maintained automatically)."
+        context:
+          type: string
+          description: "Optional extra consolidation instruction, e.g. focus on coordination lessons from today."
+        scope:
+          type: string
+          enum: ["private", "global"]
+          description: "Which memory scope to consolidate. Defaults to private project/persona memory."
+      required: ["action"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "dream_report"
+          description: "Dream sessions only: record this consolidation pass's outcome on the Memory page. Call once as the LAST step — status ok with the pages you changed, or failed with the reason. A failure is shown to the user and never retried automatically."
+        status:
+          type: string
+          enum: ["ok", "failed"]
+        summary:
+          type: string
+          description: "One or two sentences on what was consolidated (or attempted)."
+        pages:
+          type: array
+          items:
+            type: string
+          description: "Scope-relative paths of pages written or deleted in this pass."
+        ideas:
+          type: array
+          description: "Daemon-authorized dream only: grounded candidate ideas; empty means no change. No run, owner or token fields are accepted."
+          items:
+            type: object
+            additionalProperties: false
+            required: [topic, title, rationale, minimalAction]
+            properties:
+              topic:
+                type: string
+              title:
+                type: string
+              rationale:
+                type: string
+              minimalAction:
+                type: string
+        proposals:
+          type: array
+          description: "Proposals of this pass (digest-it-yourself table). Most you already acted on (needs_user=false); only schedule, or a conflict about money/external commitments/direction with equal evidence, sets needs_user=true."
+          items:
+            type: object
+            properties:
+              kind:
+                type: string
+                enum: ["clarify", "conflict", "promote", "guard", "followup", "stale", "expire", "privacy", "schedule", "skillify"]
+              evidence:
+                type: string
+                description: "Where the signal came from (log/page lines). Never copy a secret here."
+              action:
+                type: string
+                description: "One sentence: what you did, or what should be done."
+              confidence:
+                type: number
+              needs_user:
+                type: boolean
+              pages:
+                type: array
+                items:
+                  type: string
+                description: "Scope-relative pages changed for this proposal."
+            required: ["kind", "evidence", "action"]
+        error:
+          type: string
+          description: "Required when status=failed: what went wrong."
+        scope:
+          type: string
+          enum: ["private", "global"]
+      required: ["action", "status"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "migrate"
+          description: "One-shot, idempotent migration of the current memory scope to OKF: rewrite legacy type+date frontmatter, generate index.md, seed log.md."
+        scope:
+          type: string
+          enum: ["private", "global"]
+      required: ["action"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "manifest"
+          description: "Return JSON metadata for memory files, useful before recall or dream."
+        scope:
+          type: string
+          enum: ["private", "global"]
+          description: "Which memory scope to inspect. Defaults to private + global."
+      required: ["action"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "dream_prompt"
+          description: "Build the structured slow-memory consolidation prompt without calling the LLM. Useful for debugging."
+        context:
+          type: string
+          description: "Optional extra consolidation instruction."
+        scope:
+          type: string
+          enum: ["private", "global"]
+      required: ["action"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "read"
+          description: "Read a specific memory file."
+        file_path:
+          type: string
+          description: "Workspace-relative path to read, e.g. 'MEMORY.md' or 'knowledge/rust.md'."
+        scope:
+          type: string
+          enum: ["private", "global"]
+          description: "Which space to read from. 'private' (default) checks your persona's space first, falls back to global. 'global' reads from shared workspace only."
+        project:
+          type: string
+          description: "Optional absolute path of ANOTHER project root to drill into READ-ONLY (its <project>/.cteno/memory only; no global). Use it from the main conversation to look into a project listed in <project_directory>. Only recall/read/list read through it; log appends a forwarded entry to its daily log; save/overwrite/delete/dream reject it."
+      required: ["action", "file_path"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "delete"
+          description: "Delete a memory page and remove its index.md entry."
+        file_path:
+          type: string
+          description: "Workspace-relative path to delete, e.g. 'knowledge/stale-topic.md'."
+        scope:
+          type: string
+          enum: ["private", "global"]
+          description: "Which space to delete from. 'private' (default) targets the persona/project space; 'global' the shared workspace."
+      required: ["action", "file_path"]
+      additionalProperties: false
+    - type: object
+      properties:
+        action:
+          type: string
+          const: "list"
+          description: "List all memory files."
+        scope:
+          type: string
+          enum: ["private", "global"]
+          description: "Which files to list. 'private' (default) shows both private and global files with labels. 'global' shows only shared workspace files."
+        project:
+          type: string
+          description: "Optional absolute path of ANOTHER project root to drill into READ-ONLY (its <project>/.cteno/memory only; no global). Use it from the main conversation to look into a project listed in <project_directory>. Only recall/read/list read through it; log appends a forwarded entry to its daily log; save/overwrite/delete/dream reject it."
+      required: ["action"]
+      additionalProperties: false
+is_read_only: false
+is_concurrency_safe: false
+---
+
+# Persistent Memory Tool
+
+Save and recall persistent knowledge that survives across sessions.
+
+## Persona 记忆空间
+
+每个 Persona 拥有**私有记忆空间** + 可读写**全局记忆**。
+
+### 空间隔离
+
+- **私有空间** (`scope: "private"`，默认): 仅该 Persona 及其 Worker 可见
+- **全局空间** (`scope: "global"`): 所有 Persona 和 Agent 共享
+- **recall 搜索**同时覆盖私有 + 全局记忆（无需指定 scope）
+- Worker Session 继承 Persona 的私有记忆空间
+
+### MEMORY.md 兼容入口
+
+旧 `MEMORY.md` 仍可读取并注入，但不再作为 durable save 目标。新的 `save`
+必须写入独立 OKF 主题页；历史调用若仍传 `MEMORY.md`，运行时会安全重定向到
+`knowledge/general.md` 并维护索引。
+
+### 文件路径
+
+- 私有空间路径相对于 `{persona_workdir}/.cteno/`（Persona 的工作目录下）
+- 全局空间路径相对于 `workspace/`
+- 路径不能包含 `..` 或绝对路径
+
+## 记忆类型
+
+保存记忆时可指定类型标签，便于后续精准召回：
+- **user**: 用户偏好、习惯、角色（如"用户偏好暗色主题"）
+- **feedback**: 经验教训、工作规则（如"测试不要 mock 数据库"）
+- **project**: 项目架构、约定、技术决策（如"API 用 REST 不用 GraphQL"）
+- **reference**: 领域知识、外部资源指针（如"Bug 跟踪在 Linear INGEST 项目"）
+- **incident**: 事故、冲突、复盘和恢复方式
+- **workflow**: 跨 session / 多 agent 协作流程、门控和交通管制规则
+
+召回时可按类型过滤，只获取特定类型的记忆。未标记类型的旧记忆在无过滤时正常返回。
+
+## Policy (proactive usage)
+
+This tool exists so you do not rely on fragile in-chat memory.
+
+### Recall Gate (before answering)
+
+If the user's request could depend on prior context, you should **recall first** (do not guess). Triggers include:
+- The user references prior work: "上次/之前/继续/还记得/我们刚才/前面说过"
+- The user asks about preferences, decisions, rules, or ongoing project state
+- The user mentions a person/project/file path that could have prior notes
+
+Call:
+`memory({ action: "recall", query: "<3-8 keywords>" })`
+
+Recall is topic navigation, not a body-text grep. It searches the OKF index across
+private + global scopes and may omit an oversized page body under `max_chars`
+without cutting the page.
+
+When you need an exact string, identifier, error code, config key, regex, or a
+small range from a large page, **reuse the existing `grep` and `read` tools** —
+do not invent another memory action and do not keep rewriting the recall query:
+
+1. Call `memory(recall)` first so project docs are synchronized and candidate
+   Wiki pages are identified.
+2. Grep private OKF under `{current_workdir}/.cteno/memory/` (normally the
+   relative path `.cteno/memory/`) or global OKF under `~/.cteno/memory/`.
+3. Prefer `knowledge/`, `project/`, `workflow/`, `incidents/`, or `raw/docs/`;
+   do not scan `logs/` by default because daily capture is noisy source material.
+4. Use grep's returned line numbers with generic `read(offset, limit)` for the
+   needed range. Use `memory(read)` only when the complete page is required.
+
+If a result looks relevant, reasonably sized, but incomplete, follow up with:
+`memory({ action: "read", file_path: "<path>" })`
+
+### Write Gate (before final reply)
+
+If this turn produces **durable, reusable** information, you should **save it before you finalize**.
+
+Call `memory({ action: "save", file_path: "knowledge/<topic>.md", type: "<type>", content: "<durable fact>" })`.
+
+Durable means:
+- User preferences: style, language, tooling, do/don't rules
+- Project conventions/decisions: architecture choices, key commands, important paths, "always/never" rules
+- Stable environment facts that will matter later: ports, service URLs, repository layout, non-secret config choices
+- Lessons learned / postmortems
+
+Not durable:
+- One-off transient chat details ("I'm going to get coffee")
+- Large dumps or long logs (summarize instead)
+
+If unsure whether something should be remembered long-term, ask: "Should I remember that for you?"
+
+### 不要保存（关键！）
+
+- 一次性任务的分析过程或中间推理（这些是临时的，不是知识）
+- 具体的代码片段或完整文件内容（记住文件路径和关键发现即可）
+- 任务执行日志或调试输出
+- 已经存在于代码仓库或文档中的信息（不要重复存储）
+- 当前任务的上下文（任务描述、参数、执行步骤等）
+
+### Safety (what NOT to store)
+
+Never store secrets or sensitive data:
+- passwords, API keys, tokens, private keys, 2FA/OTP codes
+- personal data that the user didn't ask you to keep
+
+## Actions
+
+- **save**: Merge a durable fact into a valid OKF topic page and upsert `index.md`. Requires `content`, `type`, and a topic `file_path`. Optional `scope`.
+- **overwrite**: Replace a page with newly authored OKF content, unioning `sources[]` provenance with the existing page (read-modify-write). The merge primitive used by wiki consolidation. Requires `file_path` and `content`.
+- **recall**: Wiki recall across private + global: index-first whole pages under a Unicode-character budget (`max_chars`, default 32000). Oversized bodies are represented by their OKF path rather than cut; use existing `grep` + ranged `read`. When nothing matches, the topic `index.md` comes back as a navigation map. Requires `query`.
+- **sync_docs**: Reconcile `docs/**/*.md(x)` byte-for-byte into managed `raw/docs/**` OKF pages using source fingerprints. Project scope only; runtime injects the project path.
+- **read**: Read a specific memory file. Requires `file_path`. Optional `scope`.
+- **delete**: Delete a memory page and remove its `index.md` entry. Requires `file_path`. Optional `scope`.
+- **list**: List all memory files in the workspace. Optional `scope`.
+- **log**: Append fast memory to `logs/YYYY/MM/YYYY-MM-DD.md`. Use for fresh signals, gate decisions, external events, and handoff facts that are not ready to become durable topic memory.
+- **dream**: Run slow-memory consolidation. Spawns the `llm-wiki` librarian subagent in the background, which reads daily logs + the topic index and merges durable facts into OKF wiki pages via `overwrite` (index entries maintained automatically).
+- **migrate**: One-shot, idempotent migration of the current scope to OKF (rewrite legacy `type`+`date` frontmatter, generate `index.md`, seed `log.md`).
+- **manifest**: Return JSON metadata for memory files.
+- **dream_prompt**: Build the slow-memory prompt without running the LLM.
+- **dream_report**: (dream sessions) Record the pass outcome — `status` ok/failed, `summary`, `pages[]`, `error`, `proposals[]` ({kind, evidence, action, confidence, needs_user, pages}). Shown on the Memory page; failures are never auto-retried. Every page a session writes/deletes is journaled and undoable (`cteno-host-cli memory dream-undo <session_id>`).
+
+## Drilling into another project (read-only)
+
+`recall`, `read` and `list` accept an optional `project` — the absolute path of
+another project root. The call then reads only `<project>/.cteno/memory`
+(no global, no docs sync, nothing written). A directory without memory returns
+an empty result. `save`/`overwrite`/`delete`/`dream` reject `project`.
+
+```javascript
+memory({ action: "recall", query: "deploy checklist", project: "/Users/me/ProjectA" })
+```
+
+## Forwarding project decisions from the main conversation (append-only)
+
+The main conversation (Jelly or chat) keeps its own memory, but a decision that
+belongs to one project must also reach that project's threads. Use `log` with
+`project`:
+
+```javascript
+memory({ action: "log", project: "/Users/me/ProjectA",
+         content: "2026-10-27 决定：v2.11 起发布走 rc 通道，先在 slave 跑门禁再合 main（用户拍板）。" })
+```
+
+- It only **appends** to `<project>/.cteno/memory/logs/<today>.md` with an origin
+  note (which Jelly/session, when); a marked copy stays in your own log. The
+  project's own dream turns it into pages with `sources[]` provenance.
+- Only known projects are accepted (listed in `<project_directory>`, or a git
+  repository with `.cteno/memory`); a worktree path is redirected to its main
+  checkout. Project pages can never be written or deleted this way.
+- Write the decision self-contained (date, what, why). Cross-project facts (user
+  preferences, machines/LAN, brand wording) stay in your own/global memory.
+- A main-conversation dream also routes project entries you did not forward
+  explicitly; it is idempotent, so forwarding never duplicates.
+
+## When to Use
+
+- Save key facts, user preferences, or domain knowledge discovered during conversation
+- Recall relevant context before starting complex tasks
+- Only save truly important, reusable information (not transient task details)
+- Use `log` for fast append-only situation facts during托管/主动服务/交通管制
+- Use `dream` sparingly after several sessions or when the user returns from delegated work
+
+## File Organization
+
+Use file paths to organize by domain:
+- `knowledge/general.md` - Backward-compatible landing page for legacy `MEMORY.md` saves
+- `USER.md` - High-value user preferences and stable constraints
+- `knowledge/<topic>.md` - Domain knowledge / reusable notes
+- `logs/YYYY/MM/YYYY-MM-DD.md` - Fast daily logs / timeline notes
+- `knowledge/<topic>.md`, `workflow/<topic>.md`, `incidents/<topic>.md` - Slow dreamed memories
+
+## Examples
+
+```javascript
+// Save to private space (default for Persona)
+memory({ action: "save", file_path: "MEMORY.md", content: "- 用户偏好 Python 写脚本。\n" })
+
+// Save to global shared space
+memory({ action: "save", file_path: "USER.md", content: "- Prefers dark mode.\n", scope: "global" })
+
+// Search both private and global memories
+memory({ action: "recall", query: "Python scripting preferences" })
+
+// Read a specific file (private first, fallback to global)
+memory({ action: "read", file_path: "knowledge/rust.md" })
+
+// List all memory files (private + global with labels)
+memory({ action: "list" })
+
+// Fast memory: append a situation event
+memory({ action: "log", source: "traffic", content: "Codex session A and Claude session B are both editing auth files; traffic layer paused B until A finishes." })
+
+// Slow memory: consolidate daily logs into durable topic memories
+memory({ action: "dream", context: "Focus on cross-session coordination lessons." })
+```