dsh-supermemory 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Evandro Camargo
+
+Portions of this software are derived from the Claude Code `supermemory`
+plugin, Copyright (c) Supermemory (https://github.com/supermemoryai/claude-supermemory),
+also released under the MIT License. See NOTICE.
+
+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/NOTICE

@@ -0,0 +1,47 @@
+dsh-supermemory
+===============
+
+This package is a native DeepSeek Harness port of the Claude Code `supermemory`
+plugin, version 0.1.6.
+
+Upstream project
+----------------
+
+  Name:      supermemory (Claude Code plugin)
+  Source:    https://github.com/supermemoryai/claude-supermemory
+  Version:   0.1.6
+  Copyright: (c) Supermemory <support@supermemory.ai>
+  License:   MIT
+
+Derived material
+----------------
+
+The following files are line-by-line ports of upstream sources and retain the
+upstream behavior, wire format, prompt text, and file layout:
+
+  src/lib/api.ts               <- plugin/hooks/lib/api.js
+  src/lib/auth.ts              <- plugin/hooks/lib/auth.js
+  src/lib/colors.ts            <- plugin/hooks/lib/colors.js
+  src/lib/container-tag.ts     <- plugin/hooks/lib/container-tag.js
+  src/lib/error-helpers.ts     <- plugin/hooks/lib/error-helpers.js
+  src/lib/git-utils.ts         <- plugin/hooks/lib/git-utils.js
+  src/lib/last-session.ts      <- plugin/hooks/lib/last-session.js
+  src/lib/project-config.ts    <- plugin/hooks/lib/project-config.js
+  src/lib/settings.ts          <- plugin/hooks/lib/settings.js
+  src/lib/statusline-state.ts  <- plugin/hooks/lib/statusline-state.js
+  src/mcp-proxy.ts             <- plugin/hooks/mcp-proxy.js
+  src/statusline.ts            <- plugin/statusline.js
+  src/session-start.ts         <- plugin/hooks/session-start.js
+  src/recall.ts                <- plugin/hooks/recall-directive.js
+  src/approve.ts               <- plugin/hooks/recall-approve.js
+  src/capture.ts               <- plugin/hooks/capture.js
+  src/transcript.ts            <- plugin/hooks/lib/transcript.js
+  src/status.ts                <- plugin/commands/status.md
+  skills/supermemory-context-gatherer/SKILL.md
+                               <- plugin/agents/context-gatherer.md
+  templates/auth-success.html  <- plugin/hooks/templates/auth-success.html (verbatim)
+  templates/auth-error.html    <- plugin/hooks/templates/auth-error.html (verbatim)
+
+Supermemory, the Supermemory mark (◪), and the Supermemory brand colors belong
+to Supermemory. This is an independent port and is not an official Supermemory
+release.

package/README.md

@@ -0,0 +1,226 @@
+# dsh-supermemory
+
+Persistent memory across [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) sessions, using [Supermemory](https://supermemory.ai).
+
+A native port of the Claude Code `supermemory` plugin v0.1.6 ([supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory)). Same memories, same containers, same credentials file, same wire format — so a repository you have been working on in Claude Code arrives in DSH already remembering, and everything DSH captures shows up in Claude Code.
+
+## What it does
+
+- **Recalls at session start.** Your project's memory profile is fetched and injected before the first model request.
+- **Recalls on every prompt.** Each substantive prompt searches supermemory and injects the relevance-ranked matches, deduplicated for the life of the session, instead of waiting for the model to spend a tool call.
+- **Captures every turn.** When a turn closes, the new conversation delta is condensed into durable memory under this repository's container.
+- **Runs read-only memory tools without asking.** `search_memory`, `listSpaces`, `whoAmI` and friends never raise an approval prompt; writes still do.
+- **Mounts the hosted MCP server.** The bundled stdio proxy authenticates with the same key, so `mcp__supermemory__*` tools are available with no extra configuration.
+
+Everything recalled from supermemory is marked `◪`, and the model is instructed to keep that mark when it cites a memory.
+
+## Install
+
+Pick a profile name — `tui`, `web`, or whatever you boot with `dsh --profile <name>`. The examples use `tui`.
+
+### From npm
+
+```sh
+dsh plugin --profile tui add dsh-supermemory
+```
+
+### From a release tarball
+
+```sh
+curl -fsSLO https://github.com/nmindz/dsh-supermemory/releases/latest/download/dsh-supermemory.tgz
+dsh plugin --profile tui add ./dsh-supermemory.tgz
+```
+
+### From GitHub
+
+A git install builds the package on your machine, and pnpm blocks that until you allow it by exact commit. Run the command once to make pnpm print the key, paste the key into the profile's `pnpm-workspace.yaml`, then run it again:
+
+```sh
+dsh plugin --profile tui add github:nmindz/dsh-supermemory
+# pnpm refuses and prints an allowBuilds key — append it:
+cat >> ~/.dsh/profiles/tui/pnpm-workspace.yaml <<'YAML'
+allowBuilds:
+  dsh-supermemory@git+ssh://git@github.com/nmindz/dsh-supermemory.git#<the-sha-pnpm-printed>: true
+YAML
+dsh plugin --profile tui add github:nmindz/dsh-supermemory
+```
+
+That key is permission to run this package's build script on your machine at install time, outside any sandbox. Pin the commit SHA pnpm printed rather than a branch.
+
+### From a clone
+
+```sh
+git clone https://github.com/nmindz/dsh-supermemory.git
+cd dsh-supermemory
+pnpm install && pnpm run build
+dsh plugin --profile tui add "$PWD"
+```
+
+### After installing
+
+Restart the profile:
+
+```sh
+dsh --profile tui
+```
+
+On the first session with no stored key the browser login opens, and the key lands in `~/.supermemory-claude/credentials.json` — the same file the Claude Code plugin uses, so one login covers both. To skip the browser entirely:
+
+```sh
+export SUPERMEMORY_CC_API_KEY=sm_your_key_here
+```
+
+Confirm the plugin composed into your profile:
+
+```sh
+dsh --profile tui --dump-config | grep -A2 'dsh-supermemory'
+# == dsh-supermemory
+# - id: supermemory
+#   name: dsh-supermemory
+```
+
+Then, inside a session, check the live connection:
+
+```
+/supermemory-status
+```
+
+Nothing else is required — the bundle contributes its own patch row.
+
+### Uninstall
+
+```sh
+dsh plugin --profile tui remove dsh-supermemory
+```
+
+## Configuration
+
+Override the row in `~/.dsh/profiles/<name>/cordis.patch.yml` (or `~/.dsh/cordis.patch.yml` for every profile). A patch replaces the whole `config` block, so restate every key you want:
+
+```yaml
+- id: supermemory
+  config:
+    injectProfile: true
+    recall: true
+    capture: true
+    autoApprove: true
+    browserLogin: true
+    mcp: true
+    mcpServerName: supermemory
+    command: true
+    contextGatherer: true
+    includeSubagents: false
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `injectProfile` | `true` | Inject this project's memory profile at session start |
+| `recall` | `true` | Search supermemory with each prompt and inject the matches |
+| `capture` | `true` | Save each turn's delta back to supermemory |
+| `autoApprove` | `true` | Run read-only supermemory MCP tools without an approval prompt |
+| `browserLogin` | `true` | Open the browser login when no API key is configured |
+| `mcp` | `true` | Mount the hosted supermemory MCP server through the bundled proxy |
+| `mcpServerName` | `supermemory` | MCP namespace; tools surface as `mcp__<name>__<tool>` |
+| `command` | `true` | Register `/supermemory-status` |
+| `contextGatherer` | `true` | Register the `supermemory-context-gatherer` skill |
+| `includeSubagents` | `false` | Recall into and capture from delegated subagent sessions too |
+
+### Environment and files
+
+| Where | What |
+|---|---|
+| `SUPERMEMORY_CC_API_KEY` | API key; wins over every stored credential |
+| `SUPERMEMORY_API_URL` | API base URL (default `https://api.supermemory.ai`) |
+| `SUPERMEMORY_MCP_URL` | MCP endpoint (default `https://mcp.supermemory.ai/mcp`) |
+| `SUPERMEMORY_AUTH_URL` | Login page used by the browser flow |
+| `SUPERMEMORY_REPO_TAG` | Force one memory container tag |
+| `SUPERMEMORY_ISOLATE_WORKTREES` | `true` gives each linked git worktree its own container |
+| `SUPERMEMORY_DEBUG` | `true` logs every decision with timestamps |
+| `~/.supermemory-claude/credentials.json` | Stored API key (shared with the Claude Code plugin) |
+| `~/.supermemory-claude/settings.json` | User settings: `maxProfileItems`, `includeTools`, `recallDirective`, `signalExtraction`, `signalKeywords`, `signalTurnsBefore`, `debug` |
+| `<repo>/.claude/.supermemory-claude/config.json` | Per-project overrides: `apiKey`, `baseUrl`, `repoContainerTag`, `includeTools`, signal and recall keys |
+| `~/.supermemory-claude/statusline/` | Per-session status state, pruned after 7 days |
+| `~/.supermemory-claude/trackers/` | Per-session capture cursor |
+
+## Memory containers
+
+A container tag is derived from the git remote, normalized so `git@github.com:acme/Widgets.git` and `https://github.com/ACME/widgets/` resolve to one identity: `repo_<name>__<16 hex>`. Linked worktrees share the main checkout's container unless `SUPERMEMORY_ISOLATE_WORKTREES=true`. A repository with no remote falls back to its resolved path. `repoContainerTag` in the project config wins over everything, which is how a team shares one container.
+
+The derivation is byte-identical to the Claude Code plugin's, so both tools read and write the same container for the same repository.
+
+## Status
+
+```
+/supermemory-status
+```
+
+Reports the active project and container tag, whether a key is present and where it came from (never more than the first 6 and last 4 characters), and — because a stored key proves nothing — the result of a live `POST /v4/profile` probe, interpreted loudly: `401`/`403` means reachable but revoked, which is the silent-failure case the probe exists to catch. It also counts the registered `mcp__supermemory__*` tools.
+
+## Deeper history
+
+The `supermemory-context-gatherer` skill fans several searches out across the project's containers and returns a synthesized brief with provenance. Use it when starting significant work, resuming after time away, or when one memory search cannot cover the history the conversation needs.
+
+## How the Claude Code plugin maps onto DSH
+
+DSH has no command-hook runner, no markdown command loader, and no markdown agent loader. Each Claude Code hook becomes a typed listener on the equivalent DSH extension point:
+
+| Claude Code | DSH |
+|---|---|
+| `SessionStart` hook | `agent/session-start` listener, delivered through the first `agent/pre-step` |
+| `UserPromptSubmit` hook | `agent/pre-step` waterfall, folded onto the `enter` decision |
+| `PreToolUse` hook (`mcp__.*supermemory.*`) | `tools/pre-execute` waterfall, registered `prepend: true`, returning `{ kind: 'allow' }` |
+| `Stop` hook (async) | `agent/turn-stopping` serial listener, awaited before the turn commits |
+| `.mcp.json` server | `@deepseek-ai/dsh-mcp-client` mounted as a child plugin |
+| `commands/status.md` | `ctx.commands.register('supermemory-status')` |
+| `agents/context-gatherer.md` | `ctx.skills.register('supermemory-context-gatherer')` |
+
+DSH dispatches those points to every agent, including delegated subagents, while Claude Code's hooks only ever see the main session. Delegated sessions are therefore filtered out by default; set `includeSubagents: true` to let subagent work recall and capture too.
+
+Two further differences are worth stating plainly:
+
+**Session-start delivery is stronger here.** `agent/session-start` is an emit point that DSH never awaits, so an async memory fetch started there can miss the first request — the same gap the Claude Code hooks bridge documents. This plugin parks the fetch and the first `agent/pre-step`, which *is* awaited, folds it in. The first request always carries the project's memory.
+
+**There is no status line to install.** Claude Code's plugin writes a `statusLine` entry into `~/.claude/settings.json`; DSH's status line is host-owned and takes no plugin command. The per-session state files are written exactly as before and the animated renderer ships as an entry point, so any status bar that can run a command renders the identical line:
+
+```sh
+echo '{"session_id":"<id>"}' | node -e "import('dsh-supermemory/statusline')"
+```
+
+Live one-line notices ("3 memories loaded for widgets", "recalled 2 memories") go to the logger, because DSH exposes no transient user-message channel equivalent to a hook `systemMessage`.
+
+## Development
+
+```sh
+pnpm install
+pnpm run check      # typecheck + tests + build
+```
+
+Requires Node `^22.19.0 || >=24.0.0`.
+
+## Releasing
+
+Publishing runs from GitHub Actions through npm **trusted publishing (OIDC)** — no `NPM_TOKEN` secret exists, and every release carries provenance.
+
+One-time setup on npm: open <https://www.npmjs.com/package/dsh-supermemory/access>, add a trusted publisher, choose GitHub Actions, and enter organization `nmindz`, repository `dsh-supermemory`, workflow `.github/workflows/release.yml`, environment `npm`.
+
+Then each release is a version bump and a tag:
+
+```sh
+npm version 0.1.1 --no-git-tag-version   # edits package.json only
+git commit -am 'Release v0.1.1'
+git tag v0.1.1
+git push origin master --tags
+```
+
+The workflow refuses to publish when the tag and `package.json` version disagree, and runs `pnpm run check` before it publishes.
+
+To publish by hand instead (requires `npm login` or a configured token):
+
+```sh
+pnpm run check
+npm publish --access public
+```
+
+## License
+
+MIT. Derived from the MIT-licensed Claude Code `supermemory` plugin — see [NOTICE](NOTICE) for the file-by-file attribution. Supermemory, the `◪` mark, and the Supermemory brand belong to Supermemory; this is an independent port, not an official release.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: supermemory
+      name: 'dsh-supermemory'

package/lib/index.d.mts

@@ -0,0 +1,200 @@
+import z from "@deepseek-ai/schemastery";
+import { UserMessage } from "@deepseek-ai/dsh-llm";
+import { Context } from "@deepseek-ai/cordis";
+import { Agent } from "@deepseek-ai/dsh-agent";
+//#region src/config.d.ts
+/**
+ * Every behavior the Claude Code plugin wires through `hooks.json` is on by
+ * default here too; the flags exist so a deployment can drop one without
+ * forking the package.
+ */
+interface PluginConfig {
+  /** Inject this project's memory profile at session start. */
+  injectProfile?: boolean;
+  /** Search supermemory with each prompt and inject the top matches. */
+  recall?: boolean;
+  /** Save each turn's delta back to supermemory. */
+  capture?: boolean;
+  /** Run read-only supermemory MCP tools without an approval prompt. */
+  autoApprove?: boolean;
+  /** Open the browser login when no API key is configured. */
+  browserLogin?: boolean;
+  /** Mount the hosted supermemory MCP server through the bundled stdio proxy. */
+  mcp?: boolean;
+  /** MCP namespace; tools surface as `mcp__<mcpServerName>__<tool>`. */
+  mcpServerName?: string;
+  /** Register the `/supermemory-status` command. */
+  command?: boolean;
+  /** Register the bundled `supermemory-context-gatherer` skill. */
+  contextGatherer?: boolean;
+  /**
+   * Recall into and capture from delegated subagent sessions too. Off by
+   * default, because Claude Code's hooks only ever see the main session.
+   */
+  includeSubagents?: boolean;
+}
+declare const PluginConfig: z<PluginConfig>;
+//#endregion
+//#region src/runtime.d.ts
+/** The `{kind:'plugin'}` source stamped on every context this plugin injects. */
+declare const PLUGIN_SOURCE: {
+  readonly kind: "plugin";
+  readonly plugin: "supermemory";
+};
+/**
+ * Shared per-process state for the plugin's four behaviors.
+ *
+ * `bootstraps` holds the session-start memory fetch. `agent/session-start` is
+ * an emit point that is never awaited, so the fetch is parked here and the
+ * first `agent/pre-step` — a waterfall that IS awaited — folds the result into
+ * that step's messages. Claude Code's detached SessionStart hook can miss the
+ * first request; this cannot.
+ */
+interface SupermemoryRuntime {
+  readonly ctx: Context;
+  readonly bootstraps: Map<string, Promise<string | null>>;
+  readonly delivered: Set<string>;
+  /**
+   * User-facing one-liner. Claude Code renders these as hook `systemMessage`s;
+   * DSH exposes no equivalent transient channel, so they go to the logger and
+   * the statusline state files carry the same numbers.
+   */
+  notify(text: string): void;
+  warn(text: string): void;
+}
+declare function createRuntime(ctx: Context): SupermemoryRuntime;
+/** The session workspace an agent runs in, matching every other DSH plugin. */
+declare function cwdOf(agent: Agent | undefined): string;
+declare function sessionIdOf(agent: Agent | undefined): string;
+/**
+ * Claude Code fires SessionStart, UserPromptSubmit, and Stop for the main
+ * session only — a Task subagent gets SubagentStart/SubagentStop, which this
+ * plugin does not hook. DSH dispatches the same extension points to every
+ * agent, so delegated sessions are filtered out to keep the behavior identical.
+ */
+declare function isSubagent(agent: Agent | undefined): boolean;
+//#endregion
+//#region src/transcript.d.ts
+/** Structural view of the content blocks this module reads. */
+type TranscriptBlock = {
+  type: 'text';
+  text?: string;
+} | {
+  type: 'tool-call';
+  id?: string;
+  name?: string;
+  arguments?: string;
+} | {
+  type: 'tool-result';
+  toolCallId?: string;
+  content?: TranscriptBlock[];
+  isError?: boolean;
+} | {
+  type: string;
+  [key: string]: unknown;
+};
+/** A Claude-Code-shaped conversation entry derived from one session event. */
+interface TranscriptEntry {
+  type: 'user' | 'assistant';
+  seq: number;
+  timestamp: string;
+  content: TranscriptBlock[];
+}
+/** Structural view of the session-log events this module consumes. */
+interface TranscriptEvent {
+  type: string;
+  seq: number;
+  time?: number;
+  data?: unknown;
+}
+/** Structural view of the session this module reads its delta from. */
+interface TranscriptSession {
+  snapshotEvents(fromSeq?: number, toSeqExclusive?: number): readonly TranscriptEvent[];
+}
+interface TranscriptDelta {
+  formatted: string;
+  lastSeq: number;
+}
+/** The last captured sequence number for a session, or null before the first capture. */
+declare function getLastCapturedSeq(sessionId: string): number | null;
+declare function setLastCapturedSeq(sessionId: string, seq: number): void;
+/**
+ * Project session-log events onto the user/assistant entry list the Claude
+ * Code formatter expects. A `tool/result` event becomes a user entry carrying
+ * one tool-result block, exactly where Claude Code's transcript puts it.
+ */
+declare function entriesFromEvents(events: readonly TranscriptEvent[]): TranscriptEntry[];
+declare function formatEntry(entry: TranscriptEntry): string;
+declare function formatToolInputCompact(rawArguments: string | undefined): string;
+declare function cleanContent(text: unknown): string;
+declare function truncate(text: string | undefined, maxLength: number): string | undefined;
+declare function getTextFromEntry(entry: TranscriptEntry): string;
+interface TranscriptTurn {
+  userEntries: TranscriptEntry[];
+  assistantEntries: TranscriptEntry[];
+  allEntries: TranscriptEntry[];
+}
+declare function groupEntriesIntoTurns(entries: TranscriptEntry[]): TranscriptTurn[];
+declare function findSignalTurnIndices(turns: TranscriptTurn[], keywords: string[]): number[];
+declare function getTurnsAroundSignals(turns: TranscriptTurn[], signalIndices: number[], turnCount: number): TranscriptTurn[];
+/** Signal-extraction mode: only the turns around keyword-bearing prompts. */
+declare function formatSignalEntries(session: TranscriptSession, sessionId: string, cwd: string): TranscriptDelta | null;
+/** Default mode: every new user and assistant entry since the last capture. */
+declare function formatNewEntries(session: TranscriptSession, sessionId: string, cwd: string): TranscriptDelta | null;
+//#endregion
+//#region src/lib/api.d.ts
+interface ProfileResult {
+  profile?: {
+    static?: string[];
+    dynamic?: string[];
+  };
+  searchResults?: {
+    results?: SearchHit[];
+  };
+}
+interface SearchHit {
+  memory?: string;
+  chunk?: string;
+  content?: string;
+  text?: string;
+  title?: string;
+  filepath?: string;
+  similarity?: number;
+}
+//#endregion
+//#region src/session-start.d.ts
+declare function formatContext(profileResult: ProfileResult | null, maxItems: number, containerTag: string, projectName: string): string | null;
+//#endregion
+//#region src/recall.d.ts
+declare function shouldSkip(prompt: string): boolean;
+declare function resultText(r: SearchHit | undefined): string | null;
+declare function hashText(text: string): string;
+declare function formatRecall(results: SearchHit[], containerTag: string): string;
+/** Flatten the direct human prompt out of the messages claimed for this step. */
+declare function promptFrom(messages: readonly UserMessage[]): string;
+//#endregion
+//#region src/approve.d.ts
+/** The read-only tool name behind a supermemory MCP call, or null. */
+declare function readOnlyToolOf(toolName: string, serverName: string): string | null;
+//#endregion
+//#region src/status.d.ts
+/** Never print a full key: at most the first 6 and last 4 characters. */
+declare function maskKey(key: string): string;
+//#endregion
+//#region src/context-gatherer.d.ts
+/**
+ * The skill ships at the package root; the built bundle sits one level down
+ * and the sources one as well, so both candidates are probed.
+ */
+declare function resolveSkillDir(): string;
+/** Strip the YAML frontmatter block a filesystem skill provider would parse. */
+declare function splitFrontmatter(source: string): {
+  data: Record<string, string>;
+  body: string;
+};
+//#endregion
+//#region src/index.d.ts
+declare const name = "supermemory";
+declare function apply(ctx: Context, config: PluginConfig): void;
+//#endregion
+export { PluginConfig as Config, PluginConfig, PLUGIN_SOURCE, SupermemoryRuntime, TranscriptBlock, TranscriptDelta, TranscriptEntry, TranscriptEvent, TranscriptSession, TranscriptTurn, apply, cleanContent, createRuntime, cwdOf, entriesFromEvents, findSignalTurnIndices, formatContext, formatEntry, formatNewEntries, formatRecall, formatSignalEntries, formatToolInputCompact, getLastCapturedSeq, getTextFromEntry, getTurnsAroundSignals, groupEntriesIntoTurns, hashText, isSubagent, maskKey, name, promptFrom, readOnlyToolOf, resolveSkillDir, resultText, sessionIdOf, setLastCapturedSeq, shouldSkip, splitFrontmatter, truncate };