dsh-ai-memory

dsh-ai-memory

Memory bridge between DeepSeek Harness and ai-memory.

ai-memory shares one memory across 20+ coding agents: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and more all read and write the same wiki. DSH could only ever read it. This plugin makes DSH a full writer too.

---

What this is not

Read this first, because it decides whether this package is for you.

• It is not ai-memory. ai-memory is a separate project by a different author. This plugin does not contain it, does not bundle it, and does not replace it.
• It is not a fork of ai-memory. There is no shared code and no git relationship. ai-memory is written in Rust; this plugin is a single ~800-line JavaScript file that calls the ai-memory command-line program you install yourself. See Credits.
• It is not affiliated with, endorsed by, or supported by ai-memory's author. It is an independent third-party integration.
• It does not capture anything. It only finalizes sessions that ai-memory has already captured. Capture comes from DSH hook wiring that you install separately — see Prerequisites.

Credits

The memory engine this plugin drives is entirely the work of others:

akitaonrails/ai-memory — MIT licensed. One Rust binary that captures agent sessions through lifecycle hooks, consolidates them into a searchable Markdown wiki, and serves that memory to 20+ harnesses over MCP and HTTP.

No ai-memory code is included here. This repository contains zero lines taken from that project. It is a DSH-side adapter that shells out to the ai-memory binary, nothing more. If this plugin is useful to you, the credit belongs upstream — please star their repository.

Memory between harnesses

This is the point of the plugin, so it is worth stating precisely.

ai-memory is built on the idea that memory should follow you, not your editor. Quit Claude Code mid-task, open Codex in the same directory, and the next agent picks up a real handoff. That works because every harness writes into one shared store, and session-end consolidation turns the raw record into readable wiki pages the next agent can search.

DSH was the odd one out. ai-memory's consolidation is triggered by a session end event, and DSH never fires one — its session-terminating path exits through a signal that emits no disposal event at all. So DSH sessions landed in ai-memory as raw observations and stopped there:

Claude Code session ends ──► consolidated ──► wiki page ──► readable by every harness
DSH session ends         ──► raw observations only ──► invisible to every harness

DSH could search the memory other agents wrote, but nothing DSH did ever became memory the others could read. One-way, in the wrong direction.

This plugin closes that loop by firing the finalize step DSH never fires. With it installed:

DSH session ends ──► this plugin ──► ai-memory finalize-session ──► wiki page
                                                                      │
              Claude Code, Codex, Cursor, Gemini CLI, … ◄────────────┘

A DSH session becomes a page that Claude Code can retrieve, that a teammate's Codex can search, that shows up in the next agent's handoff brief. DSH stops being a read-only consumer of the shared memory and becomes a peer writer in it.

That is the whole value: not a new memory system, but one harness joining an existing one properly.

Prerequisites

Two things must already work. The plugin will not do either of them for you.

1. A running ai-memory server with capture wired into DSH.

Install ai-memory from upstream, then wire DSH's lifecycle hooks so events are captured. ai-memory >=3.2.0 supports DSH natively; earlier versions need the legacy Claude Code bridge configuration. A manual, single-command-string example supporting older servers is in docs/hooks-dsh.json; see its native migration notes.

Verify capture independently before blaming this plugin:

ai-memory status          # sessions and observations should be increasing
ai-memory doctor          # inside your project directory

2. The ai-memory CLI on the same machine.

That is all. It resolves its own data directory and server URL, so the default configuration needs no settings at all.

If the server is not running, this plugin logs a clear warning at startup and does nothing else. Capture failing is a separate problem with a separate cause.

Install

dsh plugin --profile web add dsh-ai-memory

From GitHub instead of npm:

dsh plugin --profile web add github:rasyidmmz/dsh-ai-memory

Restart DSH afterwards. The loader imports plugin code without a cache-buster, so an edited or newly added plugin is not picked up until the process restarts.

Confirm it loaded by searching the harness log for ai-memory:

[dsh-ai-memory] active v1.2.0 -- fast path session/disposed (zero idle cost) + ...
[dsh-ai-memory] preflight: ai-memory v3.1.1 | data_dir=... | server=127.0.0.1:49374

The preflight line is the fastest way to confirm the plugin found the same ai-memory your hooks are writing to.

From the DSH marketplace — the half this plugin does not bring

Installing from a marketplace gives you the finalize half in one row. Two things are still yours to provide, and the startup log now names whichever one is missing instead of looking merely idle:

1. ai-memory itself. The plugin shells out to the ai-memory binary; it does not bundle or install it. When the binary is missing the log says so, with the install link and the exePath key that overrides the expected location, and nothing is finalized until it appears.

2. Capture hooks. ai-memory only knows about a DSH session if DSH forwards lifecycle events to it. That wiring is one insert: row in the profile's cordis.patch.yml pointing @deepseek-ai/dsh-hooks-claude-code at a hooks file; the reference file ships in this package as docs/hooks-dsh.json. Without it ai-memory records no DSH sessions at all — so there is nothing to finalize, and the log says exactly that, with the path to that template.

   The plugin deliberately does not write that row for you. The desktop profile reloads cordis.patch.yml live, so writing it from inside a running harness is how people hang their app; and a second hooks row sitting next to one you already have would capture every session twice.

When both are in place, the preflight is one line and the rest is silent.

Configuration

Optional. The defaults are correct for a standard ai-memory install, and the plugin behaves identically with no config: block at all.

- insert:
    - id: ai-memory
      name: dsh-ai-memory
      config:
        exePath: /usr/local/bin/ai-memory   # default: platform standard location
        dataDir: /home/me/.local/share/ai-memory  # default: let the CLI decide
        # agentKind: dsh                     # optional pin; must match capture hooks
        sweep: true                         # default: true
        preflight: true                     # default: true
        timeoutMs: 120000                   # default: 120000

Legacy and native DSH capture

ai-memory 3.2.0 added AgentKind::Dsh and migration V85. Its DSH support is now listed as Hooks + MCP. Earlier releases require --agent claude-code. The UUID mapping is unchanged.

A server upgrade does not change the identity written by existing hooks. This plugin therefore reads each session's agent_kind from the local store (read-only), accepting only dsh and claude-code. That identity stays fixed through all project fallbacks and --reopen. Preflight never changes it. The sweeper also excludes unrelated harness kinds before applying its existing live-session, idle-time and UUIDv5 guards.

If the row/store or node:sqlite is unavailable, finalization falls back to claude-code, matching the shipped legacy hook template. For native capture on a remote-only store, explicitly configure agentKind: dsh.

To opt into native capture, first upgrade ai-memory to 3.2.0 or later, then change every capture command in your hooks file from --agent claude-code to --agent dsh and restart DSH (the bridge reads hooks once). Start a new session and verify its stored identity. Leave plugin agentKind unset so old captured sessions can still finalize as claude-code. The plugin does not rewrite hooks, relabel database rows, or modify your profile patch.

How it works

Two paths, deliberately asymmetric.

Fast path — an event, costing nothing while idle

When a session closes cleanly, DSH fires session/disposed. The plugin listens, derives the session's stored UUID, and calls ai-memory finalize-session.

• Idle cost: zero. No timer, no query, no process started.
• Reaction: immediate, not waiting for a scheduled sweep.

It uses session/disposed rather than the two events that fire alongside it because it is the only one carrying the full session object, so the working directory is read directly instead of being cached or guessed.

Safety net — the tiered sweeper

DSH terminates through SIGTERM, and SIGTERM fires no disposal event at all. A session open at that moment is never finalized: it stays open forever with no page. This is not hypothetical — one session with 459 observations was left behind that way.

So a sweeper exists that depends on no event: it reads ai-memory's store directly and finalizes sessions that are provably dead. Its schedule is dense at first and then eases off — 25s, 1 min, 3 min, 10 min, then every 30 min — because the only case an event misses is a session abandoned by a restart, which happens right when DSH starts.

Getting this wrong is worse than not doing it: finalizing a live session produces a page from half its content, and that page is never updated again. So four guards must all pass:

1. the session is not in this process's live-session list;
2. its last observation is more than 2 minutes old;
3. its UUID is version 5 — main sessions only, never subagents;
4. at most 10 sessions per sweep.

Guard 2 covers a second DSH window: that is a separate process, so its session is invisible here, and without the delay it would be closed mid-write.

Guard 3 has a useful side effect worth knowing if you run DSH alongside real Claude Code sessions in one repository: ai-memory stores those as version-4 UUIDs, so they can never be selected by this sweeper.

Set sweep: false to turn the whole net off; the fast path is unaffected.

The seven traps this solves

Each of these broke an earlier version, and each fix is load-bearing. They are worth listing because they are the reason a naive "just call finalize-session" plugin does not work.

1. The session id is not a raw UUID. DSH ids look like session-<uuid> and ai-memory stores them as a derived UUID v5. Passing the raw string is rejected: invalid uuid: invalid character: found 's' at 1. Child agents use a bare UUID and must be passed as is — two id shapes, two treatments.
2. The working directory must be explicit. The shell service defaults to the DSH process's own directory, not the session's repository, so scope resolves to the wrong project.
3. The project name is not always the folder's basename. Hooks write it lowercased; the CLI derives it with original casing. Repositories without an .ai-memory.toml marker only match after a lowercase retry.
4. No 2>&1. DSH runs commands with stderr unredirected, and collapsing it inside the command fails there, exiting non-zero having done nothing.
5. Subagent detection must read the session header, not the registry. The agent registry deletes an entry before announcing its disposal, so a registry lookup is always empty — including for the main session. An earlier version used it as a filter and therefore skipped every agent, doing nothing at all while logging no error.
6. Concurrent session ends must queue, not drop. Closing DSH with two sessions open fires two disposal events back to back; a naive running guard silently discards the second.
7. SIGTERM fires nothing — hence the sweeper above.

Troubleshooting

All output is prefixed [dsh-ai-memory]. Search the harness log for it.

The prefix deliberately is not [ai-memory]: ai-memory has its own logs, and an identical prefix makes it impossible to tell whose line you are reading.

If nothing appears at all, the plugin is not loaded — check the profile's cordis.patch.yml and restart DSH.

Note on finalize-session and consolidation. This plugin calls finalize-session, which is a client of the running server. It does not invoke an LLM and does not write wiki pages itself; the server does that. If pages are not appearing, check the server's own logs.

Compatibility

• DSH: developed and tested against DSH Desktop 0.2.1-rc.2 (the @deepseek-ai/dsh-desktop package), Node 24. Re-verified on 0.2.1-rc.2 on 2026-10-18 from the installed app.asar: agent/created, agent/disposed and session/disposed are still emitted, ctx.sessions.get() still returns a session whose header carries cwd, origin and delegationDepth, and ctx.shell still exposes execute() only (the run()-then-execute() capability branch below covers both). 1.0.4 and 1.1.1 were verified on 0.2.0-rc.2.

  Earlier revisions of this README said "DSH Desktop 0.9.1". That was wrong — no such DSH version exists. 0.9.1 had been read off an unrelated changelog; the package version at the time was 0.1.7-rc.2. Revisions 1.0.0-1.0.3 were tested on 0.1.7-rc.2.

• ai-memory: developed against 2.5.2 (upgraded from 2.4.0 through 2.5.2, each verified working end-to-end), re-verified on 3.1.1 on 2026-10-18. What was actually checked, not assumed:

  • finalize-session still accepts --agent, --workspace, --project, --session-id, --reopen and --json;
  • its output lines are unchanged — Finalized … on success and No open … sessions matched … when there is nothing to close, which is what this plugin's classification reads;
  • session ids are still uuid5(NAMESPACE_OID, native id) (crates/ai-memory-core/src/ids.rs:94), the exact mapping sessionIdToUuid reproduces;
  • a 2.6-era store opens under 3.1.1: it migrated to schema V83 without error, and the sweeper's query returns the same rows afterwards;
  • status --json still exists and still reports version, data_dir and bind, which the startup preflight prints. --reopen and the marker's identity key arrived in 2.5.0 and are used by 1.1.0+. See the compatibility notes below for what the upgrades changed.

• Platforms: Windows is the tested platform. Linux and macOS command construction is implemented and exercised, but not run end-to-end by the author — treat those as untested.

• No dependencies. No dependencies, no peerDependencies, so there is no build step and no allowBuilds approval on install.

• No tools, no UI. The plugin registers no model tools and draws no interface. It only listens and shells out.

Upgrading the ai-memory server from 2.x to 3.x

The CLI contract this plugin uses did not change, but the server may refuse to start after the jump, and that failure looks like the plugin's fault because finalize calls then fail with a connection error. Observed on the author's machine going 2.6.0 → 3.1.1 against a copy of the store:

provider not configured: no openai-oauth token found at <data-dir>\auth.json;
run `ai-memory auth login openai-oauth`

2.6.0 was serving with an openai-compat provider configured through llm_base_url plus environment keys; 3.1.1 wants a credential file for that provider route. The store migrated cleanly (schema V83, same pages, sessions and observations) — so this is a provider/auth step, not data loss. Run the ai-memory auth login … command the message names (or point the config at a still-valid api_key_env) before restarting the service, then check ai-memory status again.

ai-memory 2.4.0 → 2.4.1

The upgrade was run and verified on the author's machine; nothing broke. The store kept every page, session and observation, and embeddings improved (6 pages missing → 0). Two entries in that release are worth knowing here:

• CRLF pages are read correctly again — a page saved by a Windows editor used to load without its frontmatter (pinned / expires_at silently lost). Relevant on Windows, which is the tested platform.
• Session ids no longer split on letter case — D:\…\Default Project could become two separate projects. On an affected store, this release merges them.

Two shell API shapes

The plugin calls ctx.shell through one helper that accepts both shapes:

This is detected by capability (typeof ctx.shell.execute), never by version number, so a future rename cannot silently break it again. It matters because PwshLocalExecutor in 0.1.7-rc.2 exposes only execute(): without the branch, every finalize dies with shell.run is not a function — and because the failure only reaches the log, it looks like "the plugin is loaded but nothing happens" rather than an error.

Sandbox runner

DSH 0.1.7-rc.2 launches its sandbox runner through Electron, and the confined child process dies with STATUS_DLL_INIT_FAILED (0xC0000142). Measured directly, same command, correct SID:

A plugin's ctx.shell calls carry no session, so they fall back to the default workspace-write policy and always take the broken path.

The plugin therefore tries the normal, confined path first and falls back only when it sees 0xC0000142, remembering the switch. The moment DSH fixes its runner, finalize returns to being sandboxed with no change needed here.

Be aware of the trade-off: the fallback widens the CLI call's permissions beyond the workspace (danger-full-access). It is contained to the ai-memory finalize-session invocation — not the agent's own tools — and the plugin never writes files itself. If that is not acceptable in your setup, do not run it on a harness with a broken runner; there is no config switch to disable the fallback in 1.0.2.

If ai-memory changes

The plugin reads ai-memory's SQLite store directly in one place, the sweeper, and only to find abandoned sessions. If a future ai-memory release changes that schema, the sweeper logs an error and stops; the fast path is untouched because it uses no SQL at all. Set sweep: false to silence it entirely in that case.

License

MIT — see LICENSE. This license covers this plugin only. ai-memory is separately licensed (also MIT) by its own author.