dsh-memory-evolve Use Case Guide

In one line: Give the AI in DSH long-term memory that spans sessions, help you manage to-dos and skills, and even spin up a swarm of AI sessions and external AI agents to collaborate on work — the more you use it, the better it understands you; switching sessions never loses context.

This guide is organized around real workflows; each scenario explains "who it's for, what it can do, how to use it, and what you get".

Related docs: Detailed feature reference · Memory Sync · Changelog · English

---

Quick Start (Installation)

The plugin package ships with cordis.patch.yml (a dsh.bundle.patch declaration). After installing via dsh plugin add, it is automatically registered on the host side with zero manual configuration. Using the web profile as an example, two steps and you're set:

# 1. 安装到 profile（本地目录用 link:，也可用 git/registry 包地址）
dsh plugin --profile web add github:csyangwen/dsh-memory-evolve

# 2. 重启 dsh web 即生效

⚠️ Do NOT manually insert this plugin into ~/.dsh/profiles/web/cordis.patch.yml: the bundle patch is already auto-registered, and duplicating an insert with the same id will cause the loader to report a duplicate loader entry id error and fail to start. See the "Standard Installation" section of Detailed feature reference for the full explanation.

Modifying default settings (e.g., enabling in-turn memory review): use an id override in the profile's cordis.patch.yml (top-level syntax, not insert):

- id: dsh-memory-evolve
  config:
    reviewEnabled: true      # 开启回合内记忆审查（默认关）
    reviewInterval: 10       # 每 10 个用户回合审查一次

When a plugin issue prevents DSH from starting, disable it temporarily (re-enable after the fix): just add one line to the profile's cordis.patch.yml — no uninstall needed:

- id: dsh-memory-evolve
  disabled: true

Upgrading from an older version: if you previously manually inserted this plugin per the old docs, remove the insert line from the profile patch (otherwise it will duplicate the bundle's auto-registration).

Uninstall: dsh plugin --profile web remove dsh-memory-evolve — all effects are automatically cleaned up when the plugin is removed.

---

Meet It (in 30 Seconds)

Once the plugin is installed, open any session and you'll see a new row of capability tags: Memory · Skills · To-dos · Infinite Canvas · COI Scheduling · Session Broadcast · Prompts · Memory Sync · Model Settings · Bookmarks · Session Review · Web UI Settings · Memory Evolve Settings. On the AI side, a batch of tools is added: memory read/write, to-dos, skill management, local file search, session orchestration, session broadcast, external AI dispatch, prompt injection, model lookup…

In one line: AI remembers you, manages for you, works for you, and collaborates with others.

Tip: many plugin capabilities are off by default (they don't take up space in the AI's tool list). Turn them on in "Memory Evolve Settings" when needed. Most of the scenarios below are combo plays — turn on all the related features to chain them into a complete pipeline.

---

Scenario 1: Let the AI Actually Remember You (Long-term Memory)

For: everyone. Core of the plugin and foundation for all other features.

AI conversations are "one-shot": change project, open a new session, and it forgets who you are. The plugin's five-track memory gives the AI cross-session long-term working memory:

• User profile: your preferences, company, communication habits — visible to the AI every turn;
• Global facts: long-lived knowledge about environment, tools, conventions;
• Project key memories: project conventions, decisions, architecture, gotchas — auto-injected into context; important conclusions can be marked to apply only to a specific git branch;
• Project / daily log: progress auto-recorded each turn, readable on demand, traceable history.

How to use it:

1. Just talk to the AI normally — at the end of every turn it auto-writes progress to the project log and today's log;
2. When you spot an important fact, tell it "Note this: this project's deployment port is 8080" — it writes it to project key memories, and it only takes effect after you confirm — the AI never writes to memory on its own;
3. Days later, in a different session, just ask "check memory — what was the architecture decision we made last time" — it picks up right where you left off;
4. When memories pile up, tell the AI "archive that XX memory" — archived entries stop being injected into context and can be restored at any time;
5. Emotional feedback logging: your reactions to results (e.g., "great" or "why isn't it fixed yet") get logged by the AI into today's and the project's logs (a 【反馈】 line, including sentiment, task category, and your exact words) — after they accumulate, ask the AI to "analyze what I've been unhappy about recently" to see where it's doing well or not on which kinds of tasks.

What you get: the AI becomes a long-term partner who understands your work — the next day it quotes yesterday's conclusions directly, no retelling needed.

---

Scenario: Share Project Memory Across Computers (Memory Sync)

For: people working on two computers or collaborating with colleagues on the same project — no need to re-explain conclusions on every machine.

How to use it (see Memory Sync for details):

1. Enable the "Memory Sync" module in "Memory Evolve Settings → Config" (this just makes the feature visible);
2. In the project session's "Memory Sync" Tab, turn on "Sync this project" — click "Start Sync" (memory remote defaults to your code repo; it's auto-stored on a dedicated branch, keeping your code clean). Then click "Sync & Push" to complete the initial push; code is public (e.g., open source on GitHub) but you want to keep memory private? Enter a shared memory repo URL — one repo holds all projects' memories (one dedicated branch per project), fully isolating memory from code;
3. On another computer, clone the project and open it — it auto-recognizes itself (same repo URL = same project), and you can pull down and continue where you left off;
4. Write memory as usual day-to-day (real-time flush, zero latency); accumulate a batch and hit "Sync" once. Conflicts only happen when both computers edit the same memory entry; just pick "use local / use remote / keep both" in the Tab.

What you get: project memories, logs, archives, and to-dos stay consistent across devices; with a shared memory repo, global memory (user profile / daily logs / to-dos) syncs too (four independent track switches — enable what you want). Projects without sync enabled are unaffected (stay purely local).

---

Scenario 2: Multi-Project Parallel Development Without Losing a Thing (To-dos + Project Logs + Local Search)

For: developers juggling multiple projects, often blocked by "how was that approach decided?"

• Four-track to-dos: life / work / project / daily. The "project" track is isolated by working directory, so switching directories doesn't interfere. Say "remember: deploy the secondary panel to the mobile-access instance by Friday" and it auto-lands as a project to-do (with importance/urgency and a due date); the AI reminds you of due to-dos at the end of each day;
• Project logs: each project's progress is persisted and isolated by directory; logs auto-carry a [git main] branch tag for traceability;
• Local file search: tell the AI "search locally for anything I've written about similar topics" — find docs by filename (extensible to all file types); also content search: "which doc mentions XX" returns the matching file and snippet directly.

How to use it:

1. Start a new project by just chatting — project log auto-created;
2. When an idea pops up, tell the AI "remember it" — it enters the pending queue; accept or reject it in "To-dos" — you decide;
3. Can't remember? Just ask "I think a doc mentioned XX before".

What you get: run 3 projects without chaos — each project's data stays in its own directory; one question and you pick it up.

---

Scenario 3: One Person Directing a Swarm of AIs (Internal Team)

Who it's for: people who want to use the AI like a "team" — one main session directing design, frontend, backend, and testing sub-sessions.

How to use it:

1. Spin up the team: tell the main AI "create 4 sessions: design, frontend, backend, testing — put them in the same room" — it creates 4 standard sessions (visible in sidebar, take over anytime), auto-inheriting your model and working directory; at creation you can specify an Agent preset to set that session's tool set and persona;
2. Collaboration: in the room, who changed what, who finished — visible to all; member status changes (generating / idle) trigger "room activity" notifications; room messages can carry images — send a screenshot to the group, the receiving AI gets the file path via read, can inspect it, and forward to IM;
3. Dispatch & follow-up: ask "who's working, who's idle"; for an idle one say "tell frontend to send results" — the AI auto-wakes it and assigns work; no bulk wake-ups, everything directed by you or your main session;
4. Conflict prevention: when multiple sessions edit the same project, tell the AI "declare which files you'll change" before starting — others see who's touching what; on a real collision the writer gets a conflict warning, plus "workspace activity" notifications (parallel start/end, member changes) always show who's running;
5. Results back: each member sends results to the room when done; you review and confirm.

Keeping momentum (key): the main session always runs, so it can wake idle sessions anytime — follow up, collect results, dispatch the next round. Even when you're away, the team keeps moving until results come out. The only precondition: the DSH process hosting the main session stays running; if it goes idle or DSH closes, the chain stops — send a message to restart it.

What you get: one person's output becomes a team's throughput. Handoff, wake-ups, and conflict alerts are fully automated; room messages leave an auditable trail.

---

Scenario 4: Delegate Heavy Lifting to External AI Agents

Who it's for: users who need to hand big tasks (visual redesigns, code reviews, full feature development) to dedicated AI agents (Kimi / Codex / Grok / Hermes) — without being blocked, but without missing the results either.

How to use it:

1. Tell the AI "dispatch this task to grok: mobile responsive refit" — it runs asynchronously in the background and returns a task number immediately, without blocking the current session; you can keep chatting about other things;
2. Anytime in between, ask "how's the task progressing" or watch the live log stream in "COI Scheduling";
3. At dispatch time the AI can choose to attach your project memory — so the external agent also "understands the project conventions";
4. Dispatches can carry images: tell the AI "send this screenshot to grok for analysis" — attachments support local paths / remote URLs / in-session images (images you pasted in the input box); codex/kimi/hermes can actually see images (grok reads them via prompt, zcode is text-only and will explicitly refuse);
5. When done, a result summary is auto-written to the project log and today's log — work you dispatched becomes a memory asset automatically.

What you get: the AI dispatches work to the AI; you just confirm. Heavy jobs like visual overhauls, deep code reviews, and batch refactors can be offloaded, keeping the main session light.

---

Scenario 5: Internal + External Collaboration

For: tasks too big for one side alone. This is the plugin's full collaboration: internal sessions handle "work needing context and polish"; external agents handle "one-shot heavy jobs"; memory, rooms, and prompts chain them into one pipeline.

A complete real-world flow (product visual redesign):

1. Division: main session spawns frontend and testing sessions into the room; dispatches "site-wide visual redesign" to external agent Kimi;
2. External lead: Kimi runs the heavy redesign in background (no session occupied); meanwhile frontend works on data layer and page structure, not idling;
3. Handoff: Kimi finishes, summary auto-settles into project memory — main session posts design conclusions to the room; frontend reads memory for the design spec and starts integration;
4. Escalation: frontend gets stuck on a weird styling bug — main session dispatches it to Grok for a deep dive; conclusion returns to room, frontend fixes it;
5. Acceptance: testing session runs acceptance, posts results to room, you do the final confirmation.

Four integration points, freely combinable:

• Task relay: external output (summary/conclusion) auto-enters memory → internal session picks up — external does heavy lifting, internal does integration and polish;
• Issue escalation: internal hits a gnarly problem → main dispatches to external for deep dive → conclusion back to room — internal iterates fast, external crafts carefully;
• Standard unification: when dispatching to external agents, inject your curated prompts (e.g., "code review checklist", "PRD spec") — external follows your workflow, not luck;
• State sync: who's running, who's done — visible via room + workspace activity + notifications — no need to act as a human dispatcher.

What you get: a complete "external lead → internal integration → test acceptance → your confirmation" pipeline. Big tasks become a division of labor between internal and external troops.

---

Scenario 6: The AI's Self-Discipline — Prompt Injection

Who it's for: people who want to lock in "work methods that work" so that every AI (including external agents) follows the same set of processes.

The prompt library is a workflow paradigm asset library: code review, debugging, PRD, testing strategy… lock in your common work methods as prompts (categorizable, searchable, enable/disable).

How to use it:

1. AI picks & injects on its own: when the AI judges that a workflow fits the current task, it checks the prompt library, selects the fitting prompt, and injects it — "next, execute per the code review checklist"; the next turn it follows automatically, without interrupting the current reply; it can also "inject immediately" for the current turn;
2. One-click injection: in "Prompt Injection" select an entry, click "Inject once / Continuous / Immediate" — continuous means "remind the AI to work per this discipline every turn";
3. Ad-hoc injection: without creating a prompt, type a requirement to inject directly — it auto-saves to the library for reuse;
4. Dispatch with discipline: when dispatching to sub-sessions or external agents, have the AI attach the corresponding prompt — the whole team uses the same standard.

What you get: good methods no longer live only in your head or one conversation — they become a reusable "team operations manual" the AI proactively follows; you just maintain its quality.

---

Scenario 7: Long, costly sessions — bookmarks & branches

For whom: Context-cost-sensitive power users with 100+ turn sessions.

• Session bookmarks: any turn can be starred (☆); "Bookmarks" lists all (name/turn/time/summary, searchable), one click jumps to any turn — when you explore to "this conclusion is important", star it;
• Branch from any turn: the official product only supports branching from the last turn; this plugin hijacks the branch entry for any middle turn — in the bookmarks list click "Branch" (or the official branch button; middle turns pop a confirm), creating a new session via the official branch channel into the official branch lineage;
• Context usage reminder: the input box ring shows context usage in real time — ≥30% turns yellow, ≥40% red, reminding you to bookmark, branch, or start a new session.

How to use it:

1. In an exploratory session, star ☆ at key turns and name the bookmark (e.g., "Plan A review conclusion");
2. To open a new line from some mid-decision point, click "Branch" in the bookmarks list;
3. When the ring turns red, bookmark the current session and continue in a new one.

What you get: context is no longer a rope you can only scroll end-to-end, but a timeline with anchors, branches, and jumps — every turn's exploration can be precisely reused; you won't be forced to drop a good mid-conclusion just because "the session got too long".

---

Scenario 8: Stay in the Loop Away from Your Computer (Mobile + Filter + Notifications)

For whom: People who want to keep working with AI off the desktop, or juggle too many sessions to keep up.

• Mobile browser access: the DSH UI is mobile-adapted — chat area / message bubbles go full width, the input bar's "⋯" pulls up the toolbar and model selector; mobile operations match desktop;
• Session list filter: the left list can show only "active sessions", so you see who's working at a glance — also applies on desktop;
• Channel notifications (de_notify): tell the AI "notify me via Feishu when the task completes" — key results are pushed to Feishu/QQ/WeChat/WeCom; know immediately at the computer or on your phone (notification content carries an "this is a notification" marker, and can attach images/files);
• In-web notifications (de_notify channels=web): tell the AI "send me an in-web notification" — the notification lands on the bell at the top-right of the page — an unread count badge + popup list, showing "what came from which session"; click the title to jump to that session, click "View details" on long content to open a large popup for the full text; the bell is freely draggable, releasing snaps to the left/right screen edge (position remembered). Sending to web vs. Feishu etc. is the same sentence, just a different delivery destination (pass web for channels, or all to send to both);
• Direct channel send (de_channel_send): the AI can proactively send text/image/file to your IM channel anytime (no notification marker) — for "send me the generated image/doc" scenarios; all four channels (Feishu/QQ/WeChat/WeCom) supported; attachment sources: local path / remote URL / inline base64 / in-session image (sessionImage=true directly forwards the image you pasted/dragged into the DSH input box; attachmentId explicitly references, combined with de_session_images to first query what images exist in this session; requires DSH 260810+ snapshot).

What you get: Keep delegating and tracking progress without sitting at the PC — resume sessions later from the left-side list.

---

Scenario 9: Attach a Silent Reviewer to Every Session (Session Review)

For whom: People who want a "second pair of eyes" on AI work without line-by-line monitoring — especially when set rules (e.g. "state your directory before replying") are repeatedly forgotten mid-conversation.

What it can do:

• Independent reviewer: attach a dedicated review session to each one; it only observes the dialogue visible in the UI (user utterances + agent reply bodies), not thinking traces, tool-call parameters, or other internal details — like a colleague sitting by, listening but never touching the keyboard;
• Per-turn real-time review: every time the dialogue advances, the reviewer evaluates once on the full context — it is a persistent session, retaining the entire history like an ordinary long LLM conversation, never truncated, so it won't "forget what was said earlier";
• Real-time steering when needed: when the reviewer spots something worth flagging, it injects it into the current session as a user instruction — the agent treats it as you speaking and acts on it directly (decided 2026-08-13: in practice, a "non-user-instruction" marker makes the agent question the source and act weaker, so disguising it as a user instruction works best); in the GUI dialogue flow these messages appear as collapsed lines with a [severity] prefix, so you can spot at a glance which lines are the reviewer's;
• Four severity levels: info (record only, not injected by default; injection configurable) / nit (minor suggestion) / concern (worth addressing) / blocker (must be handled immediately) — not everything interrupts, only what needs saying gets said;
• New review session: one click in the panel wipes the reviewer's context and memory and restarts — you dictate the first instruction with background, and you control context length;
• Ask the reviewer directly: ask anytime from the panel, it answers immediately (the answer shows only in the review panel, not injected into the main session flow) — like an observer you can always ask;
• Four-tier constraints: system prompt (global default; view full text / edit / one-click restore) / project constraints (shared across this workspace) / session constraints (retained for this session) / this review session's constraints (wiped with "new review session") — all four are concatenated and injected; on conflict the more local tier wins;
• Auditable records: review records are persisted as JSONL; the panel's "Records" tab lets you trace them.

How to use it:

1. In "Memory Evolve Settings → Configuration," enable "Session Review" (advisorEnabled, off by default); the review model inherits the current session model by default, or you can configure advisorProvider/advisorModel separately;
2. A "Session Review" floating window appears on the session page; open the panel to see the reviewer's live review stream and context usage;
3. Set rules for the reviewer in the "Constraints" tab (e.g., a project constraint: "state which directory you are in before every reply") — changes take effect immediately on save;
4. To restart the reviewer from scratch, click "New Review Session"; to ask it something, click "Ask";
5. Agent side: review reminders appear as collapsed [severity] lines in the dialogue flow — you can see what the reviewer said and whether the agent complied.

What you get: Every AI session gains a permanent "observer" — it never interrupts your flow, just nudges the Agent back in your voice at key moments; project discipline and session constraints stay watched for you.

---

Scenario 10: Scattered materials on a single board (Infinite Canvas)

Who it's for: People whose design files, contracts, reference images, and recordings are scattered across directories and they must dig through Finder every time; and those who want AI to "see" their materials without flooding the context.

What it can do:

• Materials on the board: Three entries — path to board (paste local path), sticky notes (write on canvas, not persisted), search to board (search local files, one-click add); text files auto-read on boarding;
• See at a glance: Infinite pan/zoom canvas, free card placement, drag corner to resize; image/audio/video/text preview in-canvas, Word/PDF open with system default app;
• Single board + view filter: One physical canvas, nodes carry badges (🌐 global / 📁 project / 💬 session); default view shows "your session + current project + global", switch "Project" for that project's sessions, switch "Global" for all;
• Quick invoke: Copy node ID / title / path / reference string ([canvas:id] 标题), pass the reference to AI and it locates the material by id;
• AI bidirectional (pull-based): AI uses the de_canvas tool to query canvas by id, read content, place sticky notes in center area (marked "AI placed") — canvas content not injected into context, fetched on demand, saves tokens;
• Local path references: Files stay in place, canvas only records the pointer — source changes reflect live, deleted sources show invalid indicator;
• Safety boundaries: AI reads only boarded nodes (no arbitrary path read API); sensitive dirs (.ssh/.config etc.) refused even if boarded.

How to use:

1. Open "Infinite Canvas" (canvasEnabled, disabled by default) under "Memory Evolve Settings → Configure";
2. A "Canvas" Tab appears on the session page: path to board / sticky notes / search to board, place cards freely;
3. Click a card's "Reference" to copy the reference string, tell AI "go grab XX from the canvas" — AI uses de_canvas to query/read/place sticky notes;
4. AI-placed sticky notes land in the dashed center area, just drag them to where you want.

What you get: Say goodbye to repeatedly hunting "where was that file again" — materials consolidated on one canvas, human and AI working at the same table: you place, AI grabs; AI places, you review.

---

Other Capabilities (One-line Index)

• Self-evolving skills: Methodologies repeatedly stumbling into are automatically solidified into skills; similar tasks next time run straight through the workflow;
• Skill management: Browse/search/disable/edit all skills in the memory Tab, add custom skill directories (the former standalone plugin dsh-skills-manager has been merged into this plugin, old plugin users should uninstall the old plugin per the installation docs before upgrading);
• Infinite Canvas: Consolidate scattered files/text/images/audio-video onto one infinite canvas — local path references, single board + view filter (session/project/global), direct preview/copy/reference on the canvas; AI can also read canvas materials by id and place sticky notes in the center area (de_canvas);
• Session search: Let AI search other local AI tools' (e.g., Codex) historical sessions — just ask "what did Codex do about XX before";
• Model configuration: Plugin-side maintenance of each model's enable status, thinking level, and notes, with image input support marked (🖼 badge, obvious when AI picks a model);
• In-turn memory review: Every N rounds, AI proactively distills worth-remembering info for your confirmation — the memory library grows itself;
• Version detection & update: For multi-device/multi-user deployments, the "Version" page in the "Memory Evolve Settings" Tab auto-detects the remote release version (git tag v0.x.y), when a new version is detected a 🔴 red dot appears on the settings Tab, you decide whether to update (see "Release Versions" below);
• Session Review (Advisor): Attach an independent reviewer to each session — only observes visible UI conversation (excludes thinking/tool calls), reviews in real time each turn, nudges in user-instruction form when needed (4 levels: info/nit/concern/blocker; info defaults to log-only), continuous sessions never truncated, supports new review session/direct questions/4-level constraints/review log. Disabled by default, see Scenario 9.
• web in-site notifications: Channel notifications (de_notify) adds a web channel — AI notifications drop straight into the top-right corner bell on the webpage (unread badge + popup list + click subject to jump to session + long text large popup + drag to snap left/right), sharing the same notification semantics as IM channels like Feishu. Disabled by default, toggled with the "Notifications module" (notifyEnabled), see Scenario 8.

Full docs for each feature are in the "Guide" of its respective tab.

---

Release Versions

The plugin uses git tags as release markers (both formats: date stamp v<纯数字> like v26081302 (recommended for daily), semantic v1.2.3): pushing to main during dev never triggers update prompts, only tagged releases are detected across devices.

Release flow (developer):

# 1. 提交并推送 main（tag 必须打在已推送的 main 提交上）
git push origin main

# 2. 用发版脚本一键完成：工作树/远端同步检查 → 构建 → 全量测试 → 打 annotated tag → 推送 tag
bash ~/shell/dsh-memory-evolve-release.sh v26081302 -m "发布说明：……"

Updating on each device (user):

• Auto-detects after entering the Web UI (at most once every 24 hours, or force check via "Check for Updates"; the plugin also runs a background check on startup);
• When a new version is detected, a 🔴 red dot appears on the settings Tab; go to the "Version" page and click "Update to v26081302";
• After update completes, restart dsh web then refresh the browser (just refreshing the page won't load new code);
• After update, the plugin is on a detached HEAD (following the release tag): keep using the "Version" page's update button to upgrade, do not git pull directly;
• To switch back to the dev track: git checkout main && git pull --ff-only.

Update safety mechanism: Only accepts strictly formatted tags (v or v1.2.3) located in origin/main's history; validates local working tree is clean before update; the update process uses a cross-process lock and failure rollback, so you never get stuck in a half-updated state.

---

Three Principles

1. AI proposes, you confirm: AI-created memories, todos, skills all enter the pending queue — final say on any write that changes AI behavior stays with you;
2. No reinventing the wheel: Leave official features alone, only build what's missing and truly solves a pain point;
3. Internal/external split, complementary: Internal sessions for context-heavy work, external agents for one-shot heavy work; memory, rooms, and prompts chain them into a pipeline.

---