@jacklika/dsh-memory 0.1.7-rc.10

package/README.md

@@ -0,0 +1,84 @@
+---
+description: "The dsh memory bundle: an Obsidian-compatible Markdown vault with per-agent write namespaces, serialized writes, and git history layered over dsh-base."
+kind: "package-bundle"
+---
+
+# @jacklika/dsh-memory
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-memory` is the external Profile Bundle that mounts the complete memory chain — an Obsidian-compatible Markdown vault plus its write coordination — after `dsh-base`. Install this one package into a custom Profile; its runtime dependencies bring every member plugin.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Install the Bundle through the Harness Plugin Manager; the Profile may already exist or be created by the command:
+
+```sh
+dsh plugin --profile memory add @jacklika/dsh-memory@0.1.7-rc.10
+```
+
+Keep the Bundle after `dsh-base` and include an application layer such as `dsh-headless` or `dsh-web-app`. Semantic search stays disabled until the profile patch supplies an embeddings endpoint:
+
+```yaml
+- id: tool-memory-vector
+  disabled: false
+  config:
+    endpoint: http://localhost:11434/v1/embeddings
+    model: nomic-embed-text
+```
+
+The Bundle patch sets the vault to `<session cwd>/.plugins/memory/`; override `vaultRoot` on `tool-memory-filesystem`, `memory-queue`, `memory-git`, and `tool-memory-graph` from the profile patch if you prefer a different location.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+The bundle's substance is `cordis.patch.yml`, declared by the `dsh.bundle.patch` manifest field. Its insert list mounts the write ladder in waterfall order:
+
+1. `memory-scope` rewrites private `wiki_write` ids into `agents/<agent key>/` namespaces so agents cannot collide by construction; `shared/` prefixes pass through.
+2. `memory-queue` serializes surviving same-lane writes with an `mkdir` lock and heartbeat-counter liveness, so separate processes cannot interleave.
+3. `memory-git` commits `shared/` writes inside the lock; `nestedRepo: 'init'` keeps vault history in the vault's own `.git`, never the enclosing project repo.
+4. `tool-memory-filesystem` owns the vault: `wiki_read`, `wiki_search`, `wiki_write` with atomic publication and optional `baseVersion` conflict detection.
+5. `tool-memory-graph` adds `wiki_graph` link-graph queries.
+
+`tool-memory-vector` ships disabled because it requires an external embeddings endpoint. All git commits are local; nothing pushes.
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through each inserted row's package, which owns that row's model-facing behavior.
+
+#### KV Cache effect
+
+The bundle itself adds no request prefix; each inserted row's package owns any cache effect.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Scope, queue locks, and version checks are advisory: writers outside the waterfall (shell, Obsidian, other processes) bypass them; atomic rename and `baseVersion` bound the damage.
+- Write scope is partition-only: every agent can read the whole vault, including other agents' namespaces.
+- `tool-memory-vector` needs an external embeddings endpoint; enabling it sends note content to that endpoint.
+- Git history has no read/rollback tool yet; use `git` directly in the vault.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,84 @@
+---
+description: "dsh 记忆 bundle：在 dsh-base 之上叠加兼容 Obsidian 的 Markdown vault、按 agent 划分的写入命名空间、串行化写入与 git 历史。"
+kind: "package-bundle"
+---
+
+# @jacklika/dsh-memory
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-memory` 是外部 Profile Bundle，在 `dsh-base` 之后挂载完整记忆链——兼容 Obsidian 的 Markdown vault 及其写协调。只需把这一个包安装进自定义 Profile；它的运行时依赖会带齐所有成员插件。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+通过 Harness Plugin Manager 安装 Bundle；该命令可使用已有 Profile，也可自动创建：
+
+```sh
+dsh plugin --profile memory add @jacklika/dsh-memory@0.1.7-rc.10
+```
+
+保持 Bundle 位于 `dsh-base` 之后，并加入 `dsh-headless` 或 `dsh-web-app` 等应用层。语义搜索默认关闭，需在 profile patch 中提供 embeddings 端点后启用：
+
+```yaml
+- id: tool-memory-vector
+  disabled: false
+  config:
+    endpoint: http://localhost:11434/v1/embeddings
+    model: nomic-embed-text
+```
+
+Bundle patch 默认把 vault 设在 `<会话 cwd>/.plugins/memory/`；可在 profile patch 中覆盖 `tool-memory-filesystem`、`memory-queue`、`memory-git` 与 `tool-memory-graph` 的 `vaultRoot`。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+bundle 的实质是 `cordis.patch.yml`，由 `dsh.bundle.patch` 清单字段声明。其 insert 列表按 waterfall 顺序挂载写入阶梯：
+
+1. `memory-scope` 把私有 `wiki_write` 的 id 重写到 `agents/<agent key>/` 命名空间，使不同 agent 在结构上不可能撞车；`shared/` 前缀直接放行。
+2. `memory-queue` 用 `mkdir` 锁与心跳计数器判活串行化同 lane 的写，使不同进程无法交错。
+3. `memory-git` 在锁内提交 `shared/` 写；`nestedRepo: 'init'` 把 vault 历史保存在 vault 自己的 `.git` 中，绝不进入外层项目仓库。
+4. `tool-memory-filesystem` 拥有 vault 本体：`wiki_read`、`wiki_search`、`wiki_write`，原子发布与可选 `baseVersion` 冲突检测。
+5. `tool-memory-graph` 提供 `wiki_graph` 链接图查询。
+
+`tool-memory-vector` 默认禁用，因为它需要外部 embeddings 端点。所有 git 提交都是本地的；不会推送。
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接地，经由各插入行所属的包提供——各行自己的包负责其模型可见行为。
+
+#### KV Cache 影响
+
+bundle 自身不增加请求前缀；任何缓存影响由各插入行所属的包负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- scope、queue 锁与版本校验都是咨询性的：waterfall 之外的写入方（shell、Obsidian、其他进程）会绕过；原子 rename 与 `baseVersion` 限定损害范围。
+- 写权只划分不隔离读：每个 agent 都可读全 vault，包括其他 agent 的命名空间。
+- `tool-memory-vector` 需要外部 embeddings 端点；启用后笔记内容会发送到该端点。
+- git 历史尚无读取/回滚工具；可直接在 vault 中使用 `git`。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/cordis.patch.yml

@@ -0,0 +1,55 @@
+# The dsh-memory bundle patch: the Obsidian-compatible memory vault and its
+# write ladder over dsh-base. Insert order is the waterfall order — each
+# earlier plugin wraps the dispatches of the ones after it:
+# scope rewrites private write ids into agents/<key>/ namespaces, queue
+# serializes the surviving same-lane writes across processes, git commits
+# shared/ writes inside the lock, and the filesystem tool owns the vault
+# itself. Reads stay unscoped: every agent can read the whole vault.
+- insert:
+    - id: memory-scope
+      name: '@jacklika/dsh-memory-scope'
+
+    - id: memory-queue
+      name: '@jacklika/dsh-memory-queue'
+      config:
+        vaultRoot: '.plugins/memory'
+        crossProcessLock: true
+        laneArgument: id
+
+    - id: memory-git
+      name: '@jacklika/dsh-memory-git'
+      config:
+        vaultRoot: '.plugins/memory'
+        prefixes: ['shared/']
+        nestedRepo: init
+
+    - id: tool-memory-filesystem
+      name: '@jacklika/dsh-tool-memory-filesystem'
+      config:
+        vaultRoot: '.plugins/memory'
+        extensions: ['.md']
+        maxLinkDepth: 1
+        maxSearchResults: 20
+        indexHiddenDirs: false
+
+    - id: memory-curator
+      name: '@jacklika/dsh-memory-curator'
+
+    - id: tool-memory-graph
+      name: '@jacklika/dsh-tool-memory-graph'
+      config:
+        vaultRoot: '.plugins/memory'
+
+    # Semantic search stays off until a deployment supplies an embeddings
+    # endpoint; enable it from the profile patch layer:
+    #   - id: tool-memory-vector
+    #     disabled: false
+    #     config:
+    #       vaultRoot: '.plugins/memory'
+    #       endpoint: http://localhost:11434/v1/embeddings
+    #       model: nomic-embed-text
+    - id: tool-memory-vector
+      name: '@jacklika/dsh-tool-memory-vector'
+      disabled: true
+      config:
+        vaultRoot: '.plugins/memory'

package/lib/index.js

@@ -0,0 +1,9 @@
+/**
+ * @jacklika/dsh-memory — the memory profile bundle. The package's
+ * substance is `cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field and resolved by the profile composer through that field;
+ * this module carries no runtime API.
+ * @module @jacklika/dsh-memory
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @jacklika/dsh-memory — the memory profile bundle. The package's
+ * substance is `cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field and resolved by the profile composer through that field;
+ * this module carries no runtime API.
+ * @module @jacklika/dsh-memory
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jacklika/dsh-memory",
+  "description": "The dsh memory bundle: an Obsidian-compatible Markdown vault with per-agent write namespaces, serialized writes, and git history as a patch layer over dsh-base",
+  "version": "0.1.7-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JackLiKa/jacklika-agent-plugins-repo.git",
+    "directory": "packages/memory"
+  },
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.3.0-0"
+  },
+  "dependencies": {
+    "@jacklika/dsh-memory-curator": "0.1.0-alpha.3",
+    "@jacklika/dsh-memory-git": "0.1.0-alpha.2",
+    "@jacklika/dsh-memory-queue": "0.1.0-alpha.2",
+    "@jacklika/dsh-memory-scope": "0.1.0-alpha.1",
+    "@jacklika/dsh-tool-memory-filesystem": "0.1.3-alpha.4",
+    "@jacklika/dsh-tool-memory-graph": "0.1.0-alpha.2",
+    "@jacklika/dsh-tool-memory-vector": "0.1.0-alpha.2"
+  }
+}