dsh-evolve-in-git

dsh-evolve-in-git

English · 中文

Git-backed long-term memory and evolution plugin for DeepSeek Harness.

Contents

• What it does
• Install
• Usage
• Architecture
• Data layout
• Config
• Harness entry points
• Browser half
• Development
• Delivery notes
• License

What it does

This plugin treats a user-chosen or preconfigured Git repository as the memory store. It can write session notes, branch-specific records, and reusable skill drafts into that repo, then commit them as ordinary Git history.

Install

# example: install into the web profile
 dsh plugin --profile web add github:Kytolly/dsh-evolve-in-git

The bundle inserts one dsh-evolve-in-git row with the plugin defaults. Later profile patches can override repoPath, repoUrl, auth, and the storage roots.

Usage

Natural language

You do not need to remember tool names — describe the outcome and the model selects the right evolve_* / memory_* tool:

You say (or similar)	The model uses
"Remember: whenever X happens, do Y"	evolve_remember / memory_save
"Any memory about the deploy flow?"	evolve_recall / memory_search
"Read my recent memory history"	evolve_timeline
"Turn this warning into a reusable skill"	evolve_skill_draft → evolve_skill_promote
"What is the memory repo's current state?"	evolve_status / evolve_branches
"Undo the last memory commit"	evolve_rollback

Commands (/evolve)

For explicit, deterministic control, type /evolve <subcommand>:

/evolve remember warning "pitfall" :: <content>
/evolve search deploy
/evolve skill list
/evolve skill promote evolve-process
/evolve status
/evolve help

The full command reference is under Harness entry points.

Architecture

The package is split into a framework-free core and a thin DSH adapter:

• src/core.ts (GitMemoryCore) is the portability boundary. It depends only on Node built-ins and sibling core modules — never on @deepseek-ai/* — and resolves config from the on-disk file over the host-provided base.
• src/index.ts (GitEvolutionService) is the adapter: it registers Cordis tools, the /evolve command, the system-prompt section, the skill provider, and the config-file route, then maps every surface onto GitMemoryCore.

Module	Responsibility
src/git.ts	Spawns git: clone/open, status, branch ops, push/fetch, commit, git mv, conflicts, rollback.
src/memory.ts + src/memory-index.ts	Markdown+YAML-frontmatter scanning, a metadata index cache (HEAD + mtime signature), budgeted recall, timeline.
src/update.ts	Versioned update: a new active record plus supersedes/supersededBy; the old file is never deleted.
src/forget.ts	Soft-delete (move to archiveRoot) and restore.
src/privacy.ts	Sensitive-content detection, sensitivity classification, redaction, export filtering.
src/skill.ts	drafts/ ↔ enabled/ skill discovery; promote/demote via git mv; bundled-skill sync.
src/strategy.ts	Slug/sanitize, draft generation from a memory, evolution suggestion, preview.
src/harness.ts	/evolve command normalization/parsing plus help/usage/safety text.
src/config.ts + src/defaults.ts	Config-file read/write/merge and the plugin defaults.
src/invariant.ts	No-op invariant companion (the source of truth is the configured Git repo).
src/loopback.ts + src/config-route.ts	Loopback-only /api/evolve-git/config route for the config-file editor.
src/client/	Browser settings section (evolve-git slot) and config-file editor.

Data layout

• Memory — <repo>/<memoryRoot>/<kind>/<timestamp>-<slug>-<id>.md, one Markdown file per record with YAML frontmatter (kind, title, branch, source, tags, createdAt, id, updatedAt, status, supersedes, supersededBy, expiresAt, sensitivity) followed by the body.
• Skills — <repo>/<skillsRoot>/drafts/<name>/SKILL.md (promotable) and <repo>/<skillsRoot>/enabled/<name>/SKILL.md (discoverable). Promotion is a git mv between the two, never a copy, so it stays reversible and in history.
• Archive — <repo>/<archiveRoot>/… (same relative layout as memory); evolve_forget moves records here so they leave recall/timeline but stay recoverable. archiveRoot must remain outside memoryRoot.

Config

Web settings UI (v0.1.4+). The plugin ships a browser half that registers a first-level Settings → 演进记忆 section on the web profile's Settings page (via the settings.section slot). The form uses a SettingsScope adapter that reads and writes the per-user config file directly through the loopback-only /api/evolve-git/config route, so what the form shows is exactly what takes effect (defaults overlaid by the file) and saving writes the file immediately. Nested auth is written as one merged object, and the auth.token field is write-only (secret, redacted from read-back). Requires the profile to be restarted after install so the client manifest is rescanned.

• repoPath - the local Git checkout that stores memory and skills. Defaults to ~/.dsh-evolve-in-git/remote-memory.
• repoUrl - the remote memory repository. No personal default ships with the plugin: the built-in default is the placeholder https://github.com/<your-github-username>/<your-memory-repo>.git, so configure your own repository (see "Per-user config file" below).
• auth - Git auth settings for private access. The default profile is SSH-first and token-capable.
• memoryRoot - where memory records are written, default .dsh-evolve/memory.
• skillsRoot - where skill drafts are written, default .dsh-evolve/skills.
• defaultBranch - branch to evolve from when creating new branches, default main.
• remoteName - remote to fetch and push, default origin.
• autoCommit - whether writes auto-commit, default true.
• archiveRoot - where evolve_forget moves records, default .dsh-evolve/archive.
• recallTopK - maximum results evolve_recall returns, default 10.
• recallMinScore - minimum relevance score to keep, default 0.
• recallMaxChars - cumulative character budget for returned recall content, default 8000.
• privacyMode - write-path privacy gate for sensitive content, default ask. block rejects the write when sensitive content is detected; redact stores the redacted content (never the plaintext); ask stores the content as-is and marks its sensitivity so it can be reviewed/confirmed.
• digestEnabled - whether to inject the session-start persona+warning digest, default true.
• digestMaxRecords - maximum persona/warning records in the session-start digest, default 5.
• digestMaxChars - maximum characters of the session-start digest, default 2000.

Auth

• auth.mode: "ssh" - use ssh or a custom sshCommand.
• auth.mode: "token" - use token or a token from tokenEnv and a GitHub-style Authorization header.

Privacy write gate

Every memory write passes through the privacy gate (emails, phones, ID cards, credit cards, AWS keys, GitHub tokens, private keys, and password:-style secrets). privacyMode controls the response:

• block - reject the write when sensitive content is detected.
• redact - replace detected fragments with <REDACTED> and store that instead of the plaintext.
• ask (default) - store the content as-is and record its sensitivity so it can be reviewed and confirmed.

evolve_show/evolve_export respect the recorded sensitivity level, and exports exclude secret records by default. Records without a recorded sensitivity (written before the gate existed) are treated as secret so they are never accidentally exported.

The gate covers memory writes only (writeMemoryRecord/updateMemory, i.e. evolve_remember/memory_save/evolve_update/memory_update). Skill-draft writes (writeSkillDraft/saveSkillDraftFromRecord) intentionally do not go through the privacy gate in this release; review drafts for secrets before promoting them.

Recall scoring. evolve_recall/memory_search score a query against record metadata (title, kind, tags, branch, source) only; the body is loaded lazily for the top matches but is not part of the relevance score. The human command /evolve search <q> uses the same metadata-indexed recall, so it returns the same ranked results rather than a different matcher.

Archive constraint. archiveRoot must stay outside memoryRoot (the default .dsh-evolve/archive does). If you point archiveRoot inside memoryRoot, forgotten records are still scanned and will not disappear.

Per-user config file

Each DSH user keeps one local config file at $DSH_HOME/evolve-in-git.json (~/.dsh/evolve-in-git.json by default). It is user-local and never part of any Git repository — do not commit it. The file is the single user configuration layer: the web Settings → 演进记忆 form reads and writes exactly this file (showing the defaults overlaid by your file values, and saving writes the file immediately), and the /evolve config show|open|refresh|set <key> <value> commands edit it too. The embedded config-file editor opens the raw JSON.

Example:

{
  "repoPath": "/absolute/path/to/your/local-memory-checkout",
  "repoUrl": "https://github.com/<your-github-username>/<your-memory-repo>.git"
}

Never put access tokens in this file — use auth.tokenEnv to name an environment variable, or the web settings token field (write-only).

The web Settings → 演进记忆 section also embeds a config-file editor that opens this file directly, edits it as raw JSON, and saves it through the loopback-only /api/evolve-git/config route (saves apply immediately).

Harness entry points

The plugin targets the current Harness 0.1.1-rc.2 host contracts for commands, tools, system prompt, and invariants (peerDependencies are ^0.1.1-rc.2). Install it into a profile, then restart that profile so the bundle layer is composed.

Tools:

• evolve_connect
• evolve_status
• evolve_remember
• evolve_update
• evolve_forget
• evolve_restore
• evolve_show
• evolve_export
• evolve_branches
• evolve_branch_switch
• evolve_branch_diff
• evolve_skill_draft
• evolve_skill_list
• evolve_skill_promote
• evolve_skill_demote
• evolve_rollback
• evolve_conflicts
• evolve_resolve
• evolve_timeline
• evolve_recall
• evolve_help
• memory_search (alias of evolve_recall)
• memory_save (alias of evolve_remember)
• memory_update (alias of evolve_update)
• memory_delete (alias of evolve_forget)

Human command:

• /evolve connect
• /evolve status
• /evolve branches
• /evolve remember <kind> <title> [--expires <iso>] :: <content>
• /evolve update <id> [--merge] :: <content>
• /evolve forget <id>
• /evolve restore <id>
• /evolve config show|open|refresh|set <key> <value>
• /evolve skill draft <kind> <title> :: <content>
• /evolve skill list
• /evolve skill promote <name>
• /evolve skill demote <name>
• /evolve skill sync
• /evolve rollback <ref> [--dry]
• /evolve conflicts
• /evolve resolve <path> <ours|theirs|both>
• /evolve timeline
• /evolve search <q> [--kind k] [--tag t]
• /evolve branch switch <name> | /evolve branch diff <a> [b] | /evolve branch revert <ref>
• /evolve help

After installation, verify composition before starting a long-lived profile:

dsh --profile web --dump-config
dsh --profile web

The first command should show the evolve-git row from the plugin bundle. The second command boots the profile; once loaded, the model sees the evolve_* tools and the UI command registry exposes /evolve.

Bundled skills

The package ships the evolve-process skill under skills/. On load the plugin materializes it into the repo's <skillsRoot>/drafts/evolve-process/ (creating it only when missing); /evolve skill sync overwrites the bundled copy on demand. Promote it with /evolve skill promote evolve-process. The adapter registers the repo's <skillsRoot>/enabled/ directory as a DSH skill provider, so promoted skills become callable without any copy into ~/.dsh/skills.

Browser half

• src/client/ - the browser bundle (lib/client.js) compiled by tsc -p tsconfig.client.json && tsdown (see tsdown.config.ts); registered as a settings.section slot so the web Settings page renders the config form.
• package.json - exports["./client"] + dsh.client (platform: "web") are the manifest contract dsh-client-modules scans to include the bundle in window.__DSH_BOOT__.

Development

Requires Node.js and pnpm. The workspace sets nodeLinker: hoisted and allows the esbuild build.

pnpm install
pnpm build            # tsc (server) + tsc (client) + tsdown browser bundle
npx pnpm test         # regenerates the @deepseek-ai/dsh-tools stub, then runs tests
npx pnpm typecheck    # tsc --noEmit for both projects
npx pnpm check        # build + test (CI uses this)

The prepack script runs pnpm build, so published lib/ artifacts are always current. Tests live under tests/*.spec.ts and run with node --test via tsx.

Delivery notes

v0.6.3 finalized the MVP: metadata-indexed recall with budgets, versioned update (supersedes/supersededBy), soft-delete/restore plus expiry, reversible skill drafts with the repo enabled/ directory registered as a DSH skill provider, the block/redact/ask privacy write gate, and the memory_* aliases plus the session-start persona+warning digest.

Verification: npx pnpm check (build + test; build also typechecks) is green.

Known non-blocking TODOs

• getMemoryIndex still re-walks the memory root on cache hits (correctness over speed); a watcher-based cheap signature is future work.
• The privacy gate covers memory writes (writeMemoryRecord/updateMemory); skill-draft writes (writeSkillDraft/saveSkillDraftFromRecord) are intentionally outside the gate (documented memory-only scope).
• classifySensitivity never assigns internal; the internal export level is reachable only when a record is hand-authored with that frontmatter value.

License

MIT — see LICENSE.