Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
fix(memory): clarify Dream prompt write permissions (#5734)
chengyongru4e865b91ee04
diff --git a/nanobot/skills/memory/SKILL.md b/nanobot/skills/memory/SKILL.mdindex cf40fdad9..e71bf4dd0 100644--- a/nanobot/skills/memory/SKILL.md+++ b/nanobot/skills/memory/SKILL.md@@ -1,38 +1,20 @@---name: memory-description: Search conversation history and understand Dream-managed profile and memory files.+description: Search past conversations in the agent's history log.---# Memory-## Structure--- `SOUL.md` — Bot personality and communication style. **Managed by Dream.** Do NOT edit.-- `USER.md` — User profile and preferences. **Managed by Dream.** Do NOT edit.-- `memory/MEMORY.md` — Long-term facts (project context, important events). **Managed by Dream.** Do NOT edit.-- `memory/history.jsonl` — append-only JSONL, not loaded into context. Prefer the- built-in `grep` tool to search it.-## Search Past Events-Use the `History log` path shown in the system prompt. Always pass it to `grep`;-never substitute a different project-relative `memory/history.jsonl`, which may belong-to the selected project. Each JSONL line contains `cursor`, `timestamp`, and `content`.--- For broad searches, start with `output_mode="count"` or the default- `files_with_matches` mode before expanding to full content-- Use `output_mode="content"` plus `context_before` / `context_after` when you need the exact matching lines-- Use `fixed_strings=true` for literal timestamps or JSON fragments-- Use `head_limit` / `offset` to page through long histories--Examples (replace `<history-log-path>` with the path from the system prompt):-- `grep(pattern="keyword", path="<history-log-path>", case_insensitive=true)`-- `grep(pattern="2026-04-02 10:00", path="<history-log-path>", fixed_strings=true)`-- `grep(pattern="keyword", path="<history-log-path>", output_mode="count", case_insensitive=true)`-- `grep(pattern="oauth|token", path="<history-log-path>", output_mode="content", case_insensitive=true)`+Search the exact `History log` path from the system prompt with `grep`; a project-relative+`memory/history.jsonl` may belong to a different workspace. The log is append-only JSONL,+with `cursor`, `timestamp`, and `content` per entry, and is not loaded into context.-## Important+Start broad searches with `output_mode="count"`, then narrow by topic or date and request+matching content. Use `fixed_strings=true` for literal timestamps or JSON fragments.+Page long results with `head_limit` / `offset` and use `context_before` / `context_after`+when nearby entries matter.-- **Do NOT edit SOUL.md, USER.md, or MEMORY.md.** They are automatically managed by Dream.-- If you notice outdated information, it will be corrected when Dream runs next.-- Users can view Dream's activity with the `/dream-log` command.+Example (replace `<history-log-path>` with the path from the system prompt):+`grep(pattern="project-name", path="<history-log-path>", output_mode="content", case_insensitive=true, head_limit=20)`diff --git a/nanobot/templates/agent/dream.md b/nanobot/templates/agent/dream.mdindex 341bb0e72..150cf2976 100644--- a/nanobot/templates/agent/dream.md+++ b/nanobot/templates/agent/dream.md@@ -1,108 +1,42 @@-You are a memory consolidation engine. Your sole task is to analyze conversation history and maintain the user's long-term memory files (SOUL.md, USER.md, MEMORY.md, SKILL.md). You are ruthless about pruning: removing stale content is as important as adding new facts. You enforce MECE classification, write atomic facts, and never duplicate information across files.+You are running Dream. Consolidate the conversation history below into concise, current memory.## File routing-Do NOT guess paths. Route each fact to its canonical file:-| File | Path | Content |-|------|------|---------|-| SOUL.md | `SOUL.md` | Agent behavior rules, guardrails, interaction patterns, tool-use strategy |-| USER.md | `USER.md` | Personal attributes: identity, preferences, habits, communication style (language, length, tone) |-| MEMORY.md | `memory/MEMORY.md` | Project context: goals, architecture, strategic decisions, infrastructure overview, integrated services |-| SKILL.md | `skills/<name>/SKILL.md` | Reusable workflow templates with concrete steps, commands, and examples ([SKILL] entries only) |+Store each fact in one canonical location; merge duplicates and overlapping sections.-**Routing examples:**-- "User prefers concise replies" → USER.md-- "Reply in Chinese" → USER.md (language preference is communication style)-- "Always verify claims against source code" → SOUL.md-- "When searching, prefer grep over file listing" → SOUL.md (tool-use strategy)-- "Project targets indie developers, ~10K stars" → MEMORY.md-- "Reverse proxy on port 8080 with user deploy" → MEMORY.md (infrastructure overview)-- "Spreadsheet tool requires --id flag for sheet access" → SKILL.md (not MEMORY.md)-- "API base URL is https://api.example.com" → SKILL.md (not MEMORY.md)+| Path | Content |+|------|---------|+| `SOUL.md` | Agent behavior, guardrails, interaction patterns, tool-use strategy |+| `USER.md` | Personal attributes, habits, preferences, communication style (language, length, tone) |+| `memory/MEMORY.md` | Project goals, architecture, strategic decisions, infrastructure overview, integrated services |+| `skills/<name>/SKILL.md` | Reusable workflows with concrete steps, commands, flags, endpoints, paths, and configuration examples; apply the skill criteria below |-**Communication boundary:** Language, length, and tone preferences go to USER.md. Interaction patterns (active vs passive) and tool-use strategy go to SOUL.md.--Cross-boundary rule: no technical configs in USER.md, no user facts in SOUL.md, no operational details in MEMORY.md. If a fact fits multiple files, keep the most specific copy and remove the rest.--## MECE enforcement-- USER.md: personal attributes (identity, preferences, habits, communication style) — no technical configs, no project context-- SOUL.md: agent behavior rules, guardrails, interaction patterns, tool-use strategy — no user facts-- MEMORY.md: project context (goals, architecture, strategic decisions, infrastructure overview, integrated services) — no operational details (commands, flags, tokens, URLs)-- SKILL.md: reusable workflow templates with concrete steps, commands, and examples-- If a fact belongs in multiple files, keep it in the most specific one and remove from others+Write atomic facts and user-validated approaches, such as "has a cat named Luna", rather than descriptions like "discussed pet care".## History attribute tags-Conversation History may contain Consolidator tags. Treat them as routing and retention hints, not file content:--- [skip]: audit-only or non-SNIP content. Do not write it to SOUL.md, USER.md, MEMORY.md, or SKILL.md.-- [correction]: replace the older conflicting fact in place; do not append both versions.-- [permanent]: keep unless explicitly corrected, especially user preferences and stable identity facts.-- [durable]: keep while still true; prefer updating in place when newer evidence changes it.-- [ephemeral]: keep only when still active or recently useful; remove or ignore stale task-state details.--Always strip these bracketed tags from saved memory content.-## Skill-to-skill MECE-- If a new skill overlaps with an existing skill, merge the delta into the existing skill instead of creating a redundant one-- Check existing skill descriptions (listed above) before creating a new skill+Use these retention rules for both new history and existing memory. Tags are routing hints:-## Delete-or-keep+- [skip]: audit-only content; exclude it from saved memory.+- [correction]: replace the older conflicting fact in place.+- [permanent]: retain preferences, personality traits, stable identity facts, and current behavior rules regardless of age, unless explicitly corrected.+- [durable]: retain active project context while true. Keep architecture decisions until superseded; update changed infrastructure and remove abandoned integrations.+- [ephemeral]: retain only active or recently useful details. Keep current and next sprint goals; archive completed milestones after 30 days.-**Always delete:**-- Same fact at multiple locations — keep canonical copy only-- Merged/closed PR notes, resolved incidents, superseded info-- Verbose entries restatable in fewer words-- Overlapping or nested sections covering the same topic-- Operational details (commands, flags, tokens, URLs) that belong in a skill file-- Facts easily discoverable via a quick web search (standard library APIs, common CLI flags, public documentation, generic tutorials) — memory is for context the user *can't* look up--**Likely delete** (apply judgment):-- Same fact at different detail levels — keep most complete version only-- Debugging steps unlikely to recur-- Ephemeral facts past their useful life-- Tool/service details already captured in a skill or documented upstream-- Entries no longer referenced in recent conversations or superseded by newer facts-- Specific commit hashes, PR numbers, or issue IDs for resolved incidents--**Migrate to SKILL.md:**-- Concrete command examples, API endpoints, CLI flags, file paths-- Step-by-step procedures that recur across conversations-- Service-specific configuration patterns-- After migrating content to a skill, delete it from the source file (MEMORY.md or USER.md) to maintain MECE--**Never delete:**-- User preferences and personality traits (permanent regardless of age)-- Active project context still referenced in conversations-- Behavioral rules in SOUL.md--**Age and decay rules:**-- Sprint goals and milestones: keep current + next sprint; archive completed ones after 30 days-- Architecture decisions: keep indefinitely unless explicitly superseded-- Infrastructure details: update in place when changed; do not keep obsolete configs-- Tool/service integrations: remove if the service is no longer used+Always strip these bracketed tags from saved memory content.-When removing: prefer deleting individual items over entire sections.+Remove resolved incidents and their PR/commit references, superseded facts, stale task state, and one-off debugging details unlikely to recur. Compress verbose entries and prefer removing individual items over whole sections. Exclude conversational filler, transient weather/status/errors, and publicly documented APIs, defaults, or tutorials.-## Fact extraction-- Atomic facts: "has a cat named Luna" not "discussed pet care"-- Corrections: edit the existing entry, don't append a new one-- Conflicts: if new information contradicts an existing entry, replace the old entry in place; do not keep both versions-- Capture confirmed approaches the user validated+## Skills-## Skill discovery & creation-Flag [SKILL] only when ALL are true: repeatable workflow appeared 2+ times, involves clear steps (not vague preferences), substantial enough for its own instruction set. Check existing skills to avoid redundancy.+Create a skill only when a workflow has appeared at least twice, has concrete repeatable steps, and warrants its own instruction set. Apply these criteria to [SKILL] entries too.-For [SKILL] entries:-- Create `skills/<name>/SKILL.md`; reference `{{ skill_creator_path }}` for format-- YAML frontmatter (name, description), under 2000 words: when to use, steps, output format, example-- Do NOT overwrite existing skills — if overlapping, merge delta into the existing skill-- Skills are instruction sets with concrete values, commands, and examples. MEMORY.md keeps strategic context and high-level facts only.+- Check the available skill descriptions first; merge new details into an overlapping skill while preserving its useful content.+- Move reusable operational details out of profile/memory files into the skill, then remove the source copy.+- Follow `{{ skill_creator_path }}` for format: YAML frontmatter with name and description, under 2000 words, covering when to use it, steps, output format, and an example.-## Editing-- Current contents of SOUL.md, USER.md, and memory/MEMORY.md are provided by the agent system context. Edit those files directly; do not rely on a remembered version of a file.-- Batch changes into as few calls as possible. Surgical edits only.+## Editing and verification-## Verification-Your final summary may reference only edits confirmed by a successful tool result — that result is your proof of every change. Do not narrate edits you did not make. If a tool call failed, was skipped, or fell back to a different approach, state the failure plainly instead of claiming success. The durable audit record (`/dream-log`) is derived from the real file diff, not from this summary, so any claim not backed by an actual edit will be absent from the record.+Use the supplied file tools to read current target files, make focused edits, and verify the results. Create missing canonical files as needed; batch related changes.-Do not add: current weather, transient status, temporary errors, conversational filler, public documentation, standard library APIs, common configuration defaults, generic tutorials — anything a quick web search would surface.+Summarize only edits confirmed by successful tool results and report unresolved failures plainly. When the retained memory is already current, leave it unchanged and report that no update was needed.diff --git a/nanobot/templates/agent/identity.md b/nanobot/templates/agent/identity.mdindex e24a4dabc..e680f7e53 100644--- a/nanobot/templates/agent/identity.md+++ b/nanobot/templates/agent/identity.md@@ -4,17 +4,19 @@## Workspace{% if agent_workspace_path != workspace_path %}Nanobot's agent workspace is at: {{ agent_workspace_path }}-- Agent profile: {{ agent_workspace_path }}/SOUL.md and {{ agent_workspace_path }}/USER.md (automatically managed by Dream — do not edit directly)-- Long-term memory: {{ agent_workspace_path }}/memory/MEMORY.md (automatically managed by Dream — do not edit directly)+- Agent profile: {{ agent_workspace_path }}/SOUL.md and {{ agent_workspace_path }}/USER.md+- Long-term memory: {{ agent_workspace_path }}/memory/MEMORY.md- History log: {{ agent_workspace_path }}/memory/history.jsonl (append-only JSONL; prefer built-in `grep` for search).- Custom skills: {{ agent_workspace_path }}/skills/{% raw %}{skill-name}{% endraw %}/SKILL.md{% else %}-- Agent profile: SOUL.md and USER.md (automatically managed by Dream — do not edit directly)-- Long-term memory: memory/MEMORY.md (automatically managed by Dream — do not edit directly)+- Agent profile: SOUL.md and USER.md+- Long-term memory: memory/MEMORY.md- History log: memory/history.jsonl (append-only JSONL; prefer built-in `grep` for search).- Custom skills: skills/{% raw %}{skill-name}{% endraw %}/SKILL.md{% endif %}+Only Dream memory-consolidation tasks may edit the profile and long-term memory files listed above.+{{ platform_policy }}{% if channel == 'telegram' or channel == 'qq' or channel == 'discord' %}## Format Hintdiff --git a/tests/agent/test_context_prompt_cache.py b/tests/agent/test_context_prompt_cache.pyindex d94edfb1d..cc481d90e 100644--- a/tests/agent/test_context_prompt_cache.py+++ b/tests/agent/test_context_prompt_cache.py@@ -7,6 +7,8 @@ from datetime import datetime as real_datetimefrom importlib.resources import files as pkg_filesfrom pathlib import Path+import pytest+from nanobot.agent.context import ContextBuilderfrom nanobot.runtime_context import RuntimeContextBlock@@ -71,15 +73,20 @@ def test_selected_project_path_follows_shared_cache_prefix(tmp_path) -> None:assert prompt_a == builder.build_system_prompt(workspace=project_a)-def test_system_prompt_reflects_current_dream_memory_contract(tmp_path) -> None:[email protected]("selected_project", [False, True])+def test_system_prompt_reflects_current_dream_memory_contract(tmp_path, selected_project) -> None:workspace = _make_workspace(tmp_path)builder = ContextBuilder(workspace)+ project = tmp_path / "project" if selected_project else workspace+ project.mkdir(exist_ok=True)- prompt = builder.build_system_prompt()+ prompt = builder.build_system_prompt(workspace=project)assert "memory/history.jsonl" in prompt- assert "automatically managed by Dream" in prompt- assert "do not edit directly" in prompt+ assert (+ "Only Dream memory-consolidation tasks may edit the profile and long-term memory files "+ "listed above."+ ) in promptdef test_provider_context_appended_after_user_content(tmp_path) -> None:diff --git a/tests/agent/test_dream.py b/tests/agent/test_dream.pyindex d65c2d755..f5c9cb47c 100644--- a/tests/agent/test_dream.py+++ b/tests/agent/test_dream.py@@ -84,7 +84,6 @@ class TestBuildDreamPrompt:assert result is not Noneprompt, _ = resultassert prompt.startswith("Custom Dream prompt.")- assert "memory consolidation engine" not in promptassert "## Conversation History" in promptassert "keep this fact" in prompt@@ -111,7 +110,7 @@ class TestBuildDreamPrompt:assert result is not Noneprompt, _ = result- assert "memory consolidation engine" in prompt+ assert prompt.startswith(store.default_dream_prompt() + "\n\n## Conversation History\n")def test_truncates_long_entries_at_1000_chars(self, store):long_content = "x" * 2000