Skip to content

Your lightweight open-source personal agent.

fix(memory): clarify Dream prompt write permissions (#5734)

chengyongru4e865b91ee04
diff --git a/nanobot/skills/memory/SKILL.md b/nanobot/skills/memory/SKILL.md
index 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.md
index 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.md
index 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 Hint
diff --git a/tests/agent/test_context_prompt_cache.py b/tests/agent/test_context_prompt_cache.py
index 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_datetime
from importlib.resources import files as pkg_files
from pathlib import Path
+import pytest
+
from nanobot.agent.context import ContextBuilder
from 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 prompt
def test_provider_context_appended_after_user_content(tmp_path) -> None:
diff --git a/tests/agent/test_dream.py b/tests/agent/test_dream.py
index 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 None
prompt, _ = result
assert prompt.startswith("Custom Dream prompt.")
- assert "memory consolidation engine" not in prompt
assert "## Conversation History" in prompt
assert "keep this fact" in prompt
@@ -111,7 +110,7 @@ class TestBuildDreamPrompt:
assert result is not None
prompt, _ = 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