dsh-project-brain

English · 简体中文

A persistent project intelligence and memory plugin for DSH. It analyzes the active workspace, explains the architecture, preserves decisions and development history, and restores the right context in future sessions.

Instead of making every new conversation rediscover the repository, dsh-project-brain stores structured knowledge inside the project itself and keeps getting more useful as the project evolves.

Current release: 1.3.1 — adds import / export / local backup restore (cross-machine sync). End-to-end 20/20 smoke suites + 46/46 host-acceptance pass; data format fully backward-compatible with v1.3.0.

v1.3.1 新特性：📦 导入导出 / 备份恢复

• Dashboard 顶部新增 💾 备份 / 📥 恢复 / ↶ 回滚 三个按钮（与项目名 + techStack chip 同一行）
• 一键把整个项目脑打成 zip（含 timeline + cache + manifest + sha256 校验）→ 跨机器传文件 → 在另一台机器一键还原
• 导入前自动预览影响清单（即将覆盖的脑 / 旧脑备份路径 / rootPath 改写）；主按钮文案「覆盖并恢复」明确提醒
• 每次导入/回滚前自动备份当前脑到 .project-brain.backup-<ts>/；可随时回滚到任一历史备份
• 4 个新 Tool：project_export / project_import / project_rollback_backup / project_cleanup_backups

GitHub release · DSH community showcase · MyDSH listing

Preview

Project Brain activation entry (before first scan)

Project card with detected stack and live status

Dashboard overview with SuggestionCard and Quick Actions

Architecture tab — lane-based layered overview

Architecture tab — expanded runtime path for a single layer

TODOs and development timeline

Project memories with type badges and importance stars

Settings — vector retrieval and Embedding config

Settings — retrieval weights and probe button

Git history tab (VSCode-style)

Why use it?

AI coding sessions are usually short-lived, while real software projects are not. Important context gets scattered across conversations: why an architectural choice was made, which workaround fixed a production bug, what is currently in progress, and which files form the critical path.

dsh-project-brain turns that context into a local, workspace-scoped knowledge layer:

• Understand a repository quickly — detects languages, frameworks, tooling, entry points, manifests, README metadata, symbols, and imports.
• Explain architecture, not just folders — produces a report covering project purpose, architectural style, conceptual layers, component responsibilities, relationships, runtime flows, key files, reading order, and risks.
• Reuse the active DSH model — architecture analysis uses the provider/model already selected for the current DSH Session; no separate chat-model key is required.
• Remember across conversations — decisions, requirements, architecture notes, bugs, lessons, changes, TODOs, and timeline events persist in the workspace.
• Restore context automatically — a new Session receives high-value memories, active TODOs, and recent activity through the DSH system prompt.
• Keep workspaces isolated — the Host resolves the live Session workspace; one project's memory is never guessed from another project.
• Work without embeddings — local BM25 retrieval is the zero-configuration default. OpenAI-compatible embeddings are an optional semantic upgrade.
• Stay usable when AI is unavailable — architecture generation and memory retrieval have local fallback paths.

How it works

Active DSH Session
       │ trusted live Session cwd
       ▼
Workspace scanner ───────► project facts and source evidence
       │
       ├──► current DSH LLM ───► semantic architecture report
       │          │ unavailable / timeout / invalid output
       │          └────────────► local architecture fallback
       │
       ├──► .project-brain/ ───► memory, TODOs, timeline, architecture
       │
       ├──► context injector ──► next Session system prompt
       │
       └──► Connection RPC ────► Dashboard and TodoStrip

The browser-side UI cannot choose arbitrary filesystem paths. Runtime actions are resolved by the Host against the active DSH Session.

Local project data

Each workspace owns its data:

.project-brain/
├── project.json          # project metadata, stack, languages, and entry points
├── architecture.json     # purpose, layers, components, flows, and evidence
├── memory.jsonl          # long-term structured project memories
├── todo.jsonl            # project tasks and status
├── timeline.jsonl        # scans, memory events, TODO events, and sessions
├── codegraph.json        # optional legacy AST graph
└── cache/
    └── embeddings.jsonl  # optional, derived, and safe to rebuild

Project data survives plugin upgrades and conversation changes. Uninstalling the plugin does not delete .project-brain/.

Memory model

Memories can represent decision, requirement, architecture, change, bug, lesson, issue, or context.

Every new V2 memory includes importance, confidence, lifecycle status, source, timestamps, optional tags, and related files. Archived, superseded, and deleted memories are excluded from normal retrieval, automatic prompt injection, status counts, and the Dashboard.

The plugin writes memories through three paths:

1. The Agent records durable decisions and lessons with project_memory_add.
2. Session shutdown records a deduplicated Git change summary and uses the active DSH model to extract a small set of durable, evidence-based project facts. Credentials and non-text/tool output are excluded; unavailable or invalid model output degrades safely to Git-only memory.
3. Architecture-diff analysis can generate architecture/change memories.

The Organize Memory action first previews merge and archive candidates. It only writes changes after confirmation.

Session extraction is configurable with sessionSemanticMemoryEnabled, sessionSemanticMaxChars, sessionSemanticMaxItems, and sessionSemanticTimeoutMs. Disable it to keep Session summarization Git-only.

Retrieval

The default local retriever uses BM25 over titles, content, tags, related files, and types