@fonlan/dsh-gitmemo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fonlan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# dsh-gitmemo
+
+**English** | [**简体中文**](README.zh.md)
+
+**Git-backed long-term memory for DeepSeek Harness (dsh)** — a Cordis plugin mirroring
+[GitMemo](https://github.com/fonlan/gitmemo). The agent stores completed task outcomes as
+markdown entries in a local **`.mem`** Git repository and searches them before starting new
+work. Git is the only dependency, and no manual memory commands are ever needed.
+
+## Key Characteristics
+
+- **Extremely simple** — once installed, no manual memory commands in day-to-day tasks
+- **Fully automated** — the agent runs `init`, `search`, `read`, `write`, `delete` as part of its normal task flow
+- **Local-only & offline** — memory lives in a local `.mem` Git repository; no cloud dependency
+- **Git-only** — no runtime dependency beyond the `git` CLI
+- **Token-efficient** — reuses prior conclusions via `mem_search` instead of re-injecting context
+- **Prevents context bloat** — search-first workflow; the skill caps reads at 5 relevant memories
+- **Auditable** — every memory action is a commit in `.mem`'s Git history
+- **Traceable** — each memory can be traced and replayed from commit history
+- **Branch-aligned** — the `.mem` branch follows the project's current branch on writes
+
+## What the Plugin Provides
+
+| Piece | Description |
+| --- | --- |
+| `mem_init` | Initialize the `.mem` repository (all other tools auto-initialize) |
+| `mem_search` | Search memories: `keywords` (comma-separated), `skip` (pagination), `mode` (`and` / `or` / `auto` — AND first, OR fallback). Returns up to 20 hits as `hash\|title\|date` |
+| `mem_read` | Read one memory entry by commit hash (full markdown) |
+| `mem_write` | Store a task outcome: `title` + `content` (or `content_file` / `file`), optional `body` / `body_file`. Commits `.mem/entries/<timestamp>-<slug>.md` and aligns the `.mem` branch |
+| `mem_delete` | Delete a memory entry by commit hash (then redo and rewrite) |
+| Always-on rules section | The complete workflow rules (gitmemo's `agents-template.md` equivalent) are injected into **every** session's system prompt — no skill load needed |
+| Session-start injection | On every new **root** agent session, the N most recent memory titles (`hash\|title\|date`) are automatically injected into that session's system prompt, so prior-session context is visible before any tool call; subagents are skipped and the lookup never creates `.mem` |
+
+## Installation
+
+Requires dsh ≥ 0.1.0-rc.6 and the `git` CLI.
+
+From the npm registry (once published):
+
+```bash
+dsh plugin --profile web add @fonlan/dsh-gitmemo
+```
+
+From a local checkout (development / unpublished):
+
+```bash
+dsh plugin --profile web add /path/to/dsh-gitmemo
+```
+
+Then restart the dsh profile (e.g. restart the `dsh web` process). The plugin registers on the
+host plane, so every agent session in that profile sees the tools and the skill.
+
+### Configuration
+
+The bundle patch ships with sensible defaults; override them in the profile's
+`cordis.patch.yml`:
+
+```yaml
+- id: dsh-gitmemo
+  config:
+    memDirName: .mem       # memory repo directory name at the project root
+    searchLimit: 20        # max hits per mem_search call
+    branchAlign: true      # .mem branch follows the project branch on write
+    recentContextLimit: 5  # recent memory titles injected into each new session's system prompt (0 disables)
+    projectRoot: null      # optional explicit project root (defaults to the session cwd)
+```
+
+## Memory Location
+
+The `.mem` repository lives at the **project root** of the calling session's workspace
+(`git rev-parse --show-toplevel`, falling back to the working directory). Entries are
+markdown files under `.mem/entries/`; every operation is a commit, so the whole memory is
+readable with plain `git`:
+
+```bash
+git -C .mem log --oneline
+git -C .mem show <commit-hash>
+```
+
+> Tip: add `.mem/` to your project's `.gitignore` so the memory repository never mixes into project commits.
+
+## Agent Workflow (always-on rules)
+
+1. **Before work — search.** Extract 3-5 keywords from the request → `mem_search`. If more
+   than 5 hits are relevant, read only the 5 most likely (`mem_read`). Paginate with `skip`
+   20, 40, … when nothing relevant appears.
+2. **User unsatisfied — delete and rewrite.** `mem_delete <hash>` → redo from feedback →
+   `mem_write` a corrected entry.
+3. **End-of-session checkpoint — the only write path.** When the conversation is ending, review
+   the whole session and `mem_write` every completed repo-related task that still lacks a memory
+   and whose outcome is **valuable/reusable** (or was explicitly asked to be remembered). Never
+   duplicate an already-written entry; if a stored outcome is outdated, `mem_delete` it first,
+   then write the corrected entry. Never write for pure Q&A, incomplete tasks, non-repo work, or
+   purely operational git actions. Write all pending memories before closing the conversation.
+
+## Entry Format
+
+```markdown
+---
+date: 2026-02-19T15:10:10Z
+status: done
+repo_branch: main
+repo_commit: 9f3e1a2
+mem_branch: main
+related_paths: [src/auth/login.ts]
+tags: [auth, security]
+---
+### Original User Request
+(verbatim)
+### AI Understanding
+- Goal: / Constraints: / Out of scope:
+### Final Outcome
+- Changes/outputs summary
+```
+
+## Development
+
+```bash
+npm install
+npm run build    # tsc → lib/
+npm test         # build + engine/plugin unit tests (node:test)
+```
+
+## Layout
+
+```
+dsh-gitmemo/
+├── package.json          # npm package; dsh.bundle.patch wires the profile layer
+├── cordis.patch.yml      # composition layer: the dsh-gitmemo row
+├── src/
+│   ├── index.ts          # Cordis plugin: mem_* tools + gitmemo skill + prompt section
+│   └── mem.ts            # core engine (port of gitmemo scripts/mem.sh)
+├── lib/                  # built output (committed; used by file:/git installs)
+└── test/mem.test.mjs     # engine + plugin unit tests
+```
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,133 @@
+# dsh-gitmemo
+
+[**English**](README.md) | **简体中文**
+
+**基于 Git 的 DeepSeek Harness (dsh) 长期记忆插件** —— 一个镜像
+[GitMemo](https://github.com/fonlan/gitmemo) 功能的 Cordis 插件。Agent 会把已完成任务的结论以
+markdown 条目存入项目根目录的本地 **`.mem`** Git 仓库，并在开始新任务前先搜索既往记忆。唯一依赖
+是 Git，日常使用完全无需手动记忆命令。
+
+## 核心特性
+
+- **极其简单** —— 安装后日常任务无需任何手动记忆命令
+- **全自动** —— Agent 在正常任务流程中自动执行 `init` / `search` / `read` / `write` / `delete`
+- **纯本地、可离线** —— 记忆存于本地 `.mem` Git 仓库，无云端依赖
+- **仅依赖 Git** —— 除 `git` CLI 外无任何运行时依赖
+- **省 token** —— 通过 `mem_search` 复用既有结论，而非反复注入上下文
+- **防止上下文膨胀** —— 先搜索后工作的流程，技能规定最多只读 5 条最相关记忆
+- **可审计** —— 每次记忆操作都是 `.mem` Git 历史中的一次提交
+- **可追溯** —— 每条记忆都能从提交历史中回溯与重放
+- **分支对齐** —— 写入时 `.mem` 分支跟随项目当前分支
+
+## 插件提供的内容
+
+| 内容 | 说明 |
+| --- | --- |
+| `mem_init` | 初始化 `.mem` 仓库（其余工具都会自动初始化） |
+| `mem_search` | 搜索记忆：`keywords`（逗号分隔）、`skip`（分页）、`mode`（`and` / `or` / `auto`，auto 先 AND 后 OR 兜底）。每次最多返回 20 条 `hash\|title\|date` |
+| `mem_read` | 按提交哈希读取一条记忆的完整 markdown |
+| `mem_write` | 存储任务结论：`title` + `content`（或 `content_file` / `file`），可选 `body` / `body_file`。提交为 `.mem/entries/<时间戳>-<slug>.md` 并对齐 `.mem` 分支 |
+| `mem_delete` | 按提交哈希删除记忆条目（然后重做并重写） |
+| 常驻规则片段 | 完整工作流规则（相当于 gitmemo 的 `agents-template.md`）注入**每个**会话的系统提示词——无需加载技能即可生效 |
+| 会话开始注入 | 每个新**根** Agent 会话开始时，自动把最近 N 条记忆标题（`hash\|title\|date`）注入该系统提示词，跨会话上下文在调用任何工具前即可见；子代理被跳过，且该查询只读、绝不创建 `.mem` |
+
+## 安装
+
+需要 dsh ≥ 0.1.0-rc.6 与 `git` CLI。
+
+从 npm 仓库（发布后）：
+
+```bash
+dsh plugin --profile web add @fonlan/dsh-gitmemo
+```
+
+从本地源码目录（开发/未发布）：
+
+```bash
+dsh plugin --profile web add /path/to/dsh-gitmemo
+```
+
+然后重启对应的 dsh profile（例如重启 `dsh web` 进程）。插件注册在宿主平面，该 profile 下所有
+Agent 会话都能看到这些工具与技能。
+
+### 配置
+
+bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中覆盖：
+
+```yaml
+- id: dsh-gitmemo
+  config:
+    memDirName: .mem       # 项目根目录下记忆仓库的目录名
+    searchLimit: 20        # 每次 mem_search 返回的最大条数
+    branchAlign: true      # 写入时 .mem 分支跟随项目分支
+    recentContextLimit: 5  # 注入每个新会话系统提示词的最近记忆条数（0 表示关闭）
+    projectRoot: null      # 可选：显式项目根目录（默认取会话工作目录）
+```
+
+## 记忆存放位置
+
+`.mem` 仓库位于调用会话工作区的**项目根目录**（`git rev-parse --show-toplevel`，找不到时退回
+工作目录）。条目是 `.mem/entries/` 下的 markdown 文件；每次操作都是一次提交，整个记忆可以用
+普通 `git` 命令查看：
+
+```bash
+git -C .mem log --oneline
+git -C .mem show <commit-hash>
+```
+
+> 提示：建议把 `.mem/` 加入项目的 `.gitignore`，避免记忆仓库混入项目提交。
+
+## Agent 工作流（常驻规则）
+
+1. **开工前 —— 搜索。** 从请求中提取 3-5 个关键词 → `mem_search`。若相关结果超过 5 条，只
+   `mem_read` 最可能相关的 5 条。无相关结果时用 `skip` 20、40… 翻页。
+2. **用户不满意 —— 删除重写。** `mem_delete <hash>` → 按反馈重做 → `mem_write` 更正后的条目。
+3. **会话结束检查点 —— 唯一的写入路径。** 对话即将结束时，回顾整个会话，用 `mem_write` 写入
+   **每一条**已完成、与仓库相关、且结论**有价值/可复用**（或用户明确要求记住）但还没有记忆的任务。
+   绝不重复写已存在的条目；若已存结论已过时，先 `mem_delete` 再写更正条目。纯问答、未完成任务、
+   与仓库无关的工作、纯操作性的 git 动作一律不写。关闭会话前写完所有待写记忆。
+
+## 条目格式
+
+```markdown
+---
+date: 2026-02-19T15:10:10Z
+status: done
+repo_branch: main
+repo_commit: 9f3e1a2
+mem_branch: main
+related_paths: [src/auth/login.ts]
+tags: [auth, security]
+---
+### Original User Request
+(verbatim)
+### AI Understanding
+- Goal: / Constraints: / Out of scope:
+### Final Outcome
+- Changes/outputs summary
+```
+
+## 开发
+
+```bash
+npm install
+npm run build    # tsc → lib/
+npm test         # 构建 + 引擎/插件单元测试（node:test）
+```
+
+## 目录结构
+
+```
+dsh-gitmemo/
+├── package.json          # npm 包；dsh.bundle.patch 接入 profile 层
+├── cordis.patch.yml      # 组合层：dsh-gitmemo 行
+├── src/
+│   ├── index.ts          # Cordis 插件：mem_* 工具 + gitmemo 技能 + 提示词片段
+│   └── mem.ts            # 核心引擎（gitmemo scripts/mem.sh 的移植）
+├── lib/                  # 构建产物（已提交，供 file:/git 安装使用）
+└── test/mem.test.mjs     # 引擎 + 插件单元测试
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-gitmemo — bundle patch layer.
+#
+# Installing this package into a profile (`dsh plugin --profile <name> add @fonlan/dsh-gitmemo`)
+# appends it to `dsh.profile.bundles`; this patch is then applied as that
+# bundle's layer. The row below loads the package's main entry as a host-plane
+# plugin: it registers the `mem_init` / `mem_search` / `mem_read` /
+# `mem_write` / `mem_delete` tools on the shared tool registry, a runtime
+# `gitmemo` skill, and a system-prompt section pointing at the memory workflow.
+- insert:
+    - id: dsh-gitmemo
+      name: dsh-gitmemo
+      config:
+        memDirName: .mem
+        searchLimit: 20

package/lib/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * dsh-gitmemo — Git-backed long-term memory for DeepSeek Harness.
+ *
+ * A Cordis plugin mirroring gitmemo (https://github.com/fonlan/gitmemo):
+ * the agent stores completed task outcomes as markdown entries in a local
+ * `.mem` git repository and searches them before starting new work.
+ *
+ * This plugin registers on the host plane:
+ *  - five model-facing tools: `mem_init`, `mem_search`, `mem_read`,
+ *    `mem_write`, `mem_delete` (backed by {@link GitMemo});
+ *  - an always-on system-prompt section with the full memory workflow rules;
+ *  - a per-session seed of the most recent memory titles.
+ *
+ * @module dsh-gitmemo
+ */
+import z from "@deepseek-ai/schemastery";
+/** Cordis plugin name. */
+declare const name = "dsh-gitmemo";
+/** Host services this plugin needs. */
+declare const inject: string[];
+/** Plugin configuration (all optional). */
+declare const Config: z<Schemastery.ObjectS<{
+    /** Name of the memory repo directory at the project root. Default ".mem". */
+    memDirName: z<string, string>;
+    /** Max search hits per mem_search call. Default 20. */
+    searchLimit: z<number, number>;
+    /** Align the .mem branch with the project branch on writes. Default true. */
+    branchAlign: z<boolean, boolean>;
+    /** Number of most recent memory titles injected into each new session's system prompt (0 disables). Default 5. */
+    recentContextLimit: z<number, number>;
+    /** Optional explicit project root; defaults to the calling session's cwd. */
+    projectRoot: z<string, string>;
+}>, Schemastery.ObjectT<{
+    /** Name of the memory repo directory at the project root. Default ".mem". */
+    memDirName: z<string, string>;
+    /** Max search hits per mem_search call. Default 20. */
+    searchLimit: z<number, number>;
+    /** Align the .mem branch with the project branch on writes. Default true. */
+    branchAlign: z<boolean, boolean>;
+    /** Number of most recent memory titles injected into each new session's system prompt (0 disables). Default 5. */
+    recentContextLimit: z<number, number>;
+    /** Optional explicit project root; defaults to the calling session's cwd. */
+    projectRoot: z<string, string>;
+}>>;
+interface ResolvedConfig {
+    memDirName: string;
+    searchLimit: number;
+    branchAlign: boolean;
+    recentContextLimit: number;
+    projectRoot?: string;
+}
+/** Shape of the agent payload received by an `agent/created` listener. */
+interface CreatedAgent {
+    id: string;
+    session?: {
+        header?: {
+            cwd?: string;
+            delegationDepth?: number;
+        };
+    };
+    ctx: {
+        systemPrompt: {
+            context(section: {
+                name: string;
+                order: number;
+                text: string;
+            }): unknown;
+        };
+    };
+}
+/**
+ * Register the plugin: tools, always-on rules, and session-start seed.
+ * @param ctx - registrant context carrying the host tool/prompt services.
+ * @param config - plugin configuration (defaults applied by the loader).
+ */
+declare function apply(ctx: {
+    tools: {
+        register(tool: unknown): unknown;
+    };
+    systemPrompt: {
+        section(section: {
+            name: string;
+            order: number;
+            text: string;
+        }): unknown;
+    };
+    on(event: string, handler: (payload: {
+        agent: CreatedAgent;
+    }) => void): unknown;
+    logger: {
+        warn(message: string): void;
+    };
+}, config?: Partial<ResolvedConfig>): Promise<void>;
+export { Config, apply, inject, name };