@deepseek-ai/dsh-tool-memory

Tool Memory

DeepSeek Harness 的持久化记忆插件，使智能体能够跨会话存储和召回信息——提供具备原子存储、验证和并发安全读取功能的 DSH 原生工具

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:disc0nct/dsh-memory-plugin#0005ac2e190379d457699fa534760927206f3024

兼容性与来源证明

Tool Memory 以 @deepseek-ai/dsh-tool-memory 发布，当前版本为 1.3.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: any
发布来源: github
Registry 更新时间: 2026/8/21

版本

1.3.1stable

2026/8/21

1.2.0stable

2026/8/20

README

@deepseek-ai/dsh-tool-memory

A persistent memory plugin for DeepSeek Harness (DSH) that enables agents to store and recall information across sessions, similar to the memory system in Hermes agent AI.

Features

🧠 Persistent Storage: Memories are saved to disk and survive across sessions
🔍 Flexible Search: Hybrid keyword+semantic (token Jaccard + substring) with mode: hybrid|keyword|semantic
🏷️ Categorization: Organize memories with optional categories (kebab-case, defaults to general)
📋 Seven Tools: memory_store, memory_search, memory_get, memory_list, memory_delete, memory_clear, memory_stats
🔄 Atomic Writes: write+rename with mkdir -p, corrupt-file recovery to *.corrupt.*, orphan *.tmp.* sweep (>1h) on load
⚡ Performance: In-memory mtime cache, timestampMs numeric sort, inverted index Map<token,Set<id>> for sub-linear hybridSearch, MAX_FACTS cap, timeoutMs:5000, isConcurrencySafe for reads
✅ Validation & Safety: kebab-case keys, MAX_TIMESTAMP_MS, timestampMs auto-generated, MemoryPluginError + 3× retry for EACCES/EBUSY, memory_clear confirm:true, withWriteLock per-file serialization
🧩 Modular & DSH-Native: lib/config|storage|validation|search/scoring|tools/*, peerDependencies to avoid dual-instance prepare bug, graceful fallback to linear scan

Installation

This package ships a dsh.bundle manifest, so it can be installed as a regular profile bundle.

As a DSH Plugin

Add the plugin to your DSH profile (this runs pnpm add in the profile directory, so a git URL works):
```
dsh plugin --profile <your-profile> add github:disc0nct/dsh-memory-plugin
```

{
  "dependencies": {
    "@deepseek-ai/dsh-tool-memory": "github:disc0nct/dsh-memory-plugin"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@deepseek-ai/dsh-tool-memory"
      ]
    }
  }
}

Boot the profile:
```
dsh --profile <your-profile>
```

Usage

Available Tools

Once installed, the following tools become available to your DSH agent:

`memory_store`

Save an important fact to long-term memory.

// Store a user preference
await ctx.tools.memory_store({
  key: "user-name",
  value: "Alice",
  category: "preferences"
});

// Store project information
await ctx.tools.memory_store({
  key: "project-language",
  value: "TypeScript",
  category: "project"
});

// Store a decision
await ctx.tools.memory_store({
  key: "api-decision",
  value: "Use REST API for simplicity",
  category: "decisions"
});

`memory_search`

Search for memories by keyword, category, or semantic paraphrase (hybrid keyword+token Jaccard ranking, dependency-free).

// Search all memories
const results = await ctx.tools.memory_search({
  query: "Alice"
});

// Search by category
const results = await ctx.tools.memory_search({
  category: "preferences"
});

// Combined search
const results = await ctx.tools.memory_search({
  query: "API",
  category: "decisions",
  limit: 5
});

// Semantic paraphrase: "fav color" matches "favorite-color"
const results = await ctx.tools.memory_search({
  query: "fav color",
  mode: "hybrid" // | "keyword" | "semantic" (default: "hybrid")
});

// Force exact substring only
const results = await ctx.tools.memory_search({
  query: "color",
  mode: "keyword"
});

`memory_get`

Fast exact lookup by key (vs memory_search scan).

const { found, fact } = await ctx.tools.memory_get({ key: "user-name" });
if (found) console.log(fact.value);

`memory_list`

List all stored memories (most recent first, optionally filtered).

// List all memories
const memories = await ctx.tools.memory_list();

// List memories by category
const memories = await ctx.tools.memory_list({
  category: "project"
});

`memory_delete`

Delete a specific memory by its key.

await ctx.tools.memory_delete({
  key: "user-name"
});

`memory_clear`

Clear ALL stored memories (requires explicit confirmation).

// cancelled without confirm
await ctx.tools.memory_clear(); // { cleared:false, count: N }

// confirmed
await ctx.tools.memory_clear({ confirm: true }); // { cleared:true, count: N }

`memory_stats`

Get health stats (count, per-category, oldest/newest, file size).

const stats = await ctx.tools.memory_stats();
console.log(stats.count, stats.categories); // {count: 12, categories:{project:5}}

Memory Storage Format

Memories are stored in ~/.dsh/memory.json with this structure:

{
  "facts": [
    {
      "id": "unique-identifier",
      "key": "user-name",
      "value": "Alice",
      "category": "preferences",
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Configuration

The memory file defaults to $DSH_HOME/memory.json (or ~/.dsh/memory.json when DSH_HOME is unset). Override it in the profile's patch layer ($DSH_HOME/profiles/<your-profile>/cordis.patch.yml):

- id: tool-memory
  config:
    memoryPath: /absolute/path/to/memory.json

Examples

Remembering User Information

// When user introduces themselves
if (userMessage.includes("my name is")) {
  const name = extractName(userMessage);
  await ctx.tools.memory_store({
    key: "user-name",
    value: name,
    category: "identity"
  });
}

// Later, when needing to address the user
const memory = await ctx.tools.memory_search({
  query: "name",
  category: "identity"
});
if (memory.results.length > 0) {
  await ctx.tools.memory_store({
    key: "greeting-used",
    value: `Hello ${memory.results[0].value}!`,
    category: "interaction"
  });
}

Project Context Tracking

// When starting work on a project
await ctx.tools.memory_store({
  key: "project-start",
  value: `Started work on ${projectName} at ${new Date().toISOString()}`,
  category: "project"
});

// When making a technical decision
await ctx.tools.memory_store({
  key: "tech-decision-db",
  value: "Selected PostgreSQL for reliability",
  category: "decisions"
});

// Later, when continuing work
const projectInfo = await ctx.tools.memory_list({
  category: "project"
});

How It Works

The plugin implements persistent memory by:

File Storage: Atomic writeFile(tmp)+rename to ~/.dsh/memory.json (no double-write), mkdir -p, max 5000 facts, orphan *.tmp.* sweep (>1h) via readdir on load
Concurrency: Per-file withWriteLock Promise queue (lib/storage.js:47-62) serializes store/delete/clear load→mutate→save — prevents lost updates; reads remain isConcurrencySafe
Timestamps: timestamp (ISO) + timestampMs (numeric, Date.now()) generated internally; compareRecent prefers timestampMs (no Date.parse per compare); old files migrated on load (backfill timestampMs via Date.parse)
Performance: mtime+size cache (lib/storage.js:105-115), inverted index Map<token,Set<id>> + Map<id,{hash,tokens}> cache (lib/search/scoring.js:50-120) — hybridSearch union of id sets → sub-linear, fallback linear on miss
Efficient Lookups: Hybrid search token Jaccard + substring boosts then timestampMs desc; empty query → recency
Upsert: memory_store replaces existing key and moves to most-recent
Validation: key/category kebab-case, value ≤10000, category ≤32, timestampMs 0..4102444800000 (lib/validation.js:5-27), MemoryPluginError + 3× retry for transient EACCES/EBUSY
Recovery: SyntaxError → *.corrupt.* backup + empty; ENOENT → empty; graceful degradation index→linear
Modular Layout: lib/config.js, lib/storage.js, lib/validation.js, lib/search/scoring.js, lib/tools/* (DSH apply re-exports)
DSH Idioms: Config via schemastery, defineTool timeoutMs:5000 isConcurrencySafe hints

Requirements

DeepSeek Harness (DSH) v0.1.0-rc.8 or later
Node.js v18.0.0 or later (uses crypto.randomUUID, fs/promises.rename/stat)
Peer dependencies:
- @deepseek-ai/cordis: ^4.0.1
- @deepseek-ai/dsh-tools: ^0.1.0-rc.8
- @deepseek-ai/schemastery: ^3.18.1

License

MIT License - feel free to use, modify, and distribute this plugin.

Development

To contribute to this plugin:

Fork the repository
Create a feature branch
Make your changes
Ensure all tests pass (if applicable)
Submit a pull request

Credits

Inspired by the memory systems in agents like Hermes AI, this plugin brings similar long-term memory capabilities to the DeepSeek Harness ecosystem.

Built with ❤️ for the DSH community

README

@deepseek-ai/dsh-tool-memory

A persistent memory plugin for DeepSeek Harness (DSH) that enables agents to store and recall information across sessions, similar to the memory system in Hermes agent AI.

Features

🧠 Persistent Storage: Memories are saved to disk and survive across sessions
🔍 Flexible Search: Hybrid keyword+semantic (token Jaccard + substring) with mode: hybrid|keyword|semantic
🏷️ Categorization: Organize memories with optional categories (kebab-case, defaults to general)
📋 Seven Tools: memory_store, memory_search, memory_get, memory_list, memory_delete, memory_clear, memory_stats
🔄 Atomic Writes: write+rename with mkdir -p, corrupt-file recovery to *.corrupt.*, orphan *.tmp.* sweep (>1h) on load
⚡ Performance: In-memory mtime cache, timestampMs numeric sort, inverted index Map<token,Set<id>> for sub-linear hybridSearch, MAX_FACTS cap, timeoutMs:5000, isConcurrencySafe for reads
✅ Validation & Safety: kebab-case keys, MAX_TIMESTAMP_MS, timestampMs auto-generated, MemoryPluginError + 3× retry for EACCES/EBUSY, memory_clear confirm:true, withWriteLock per-file serialization
🧩 Modular & DSH-Native: lib/config|storage|validation|search/scoring|tools/*, peerDependencies to avoid dual-instance prepare bug, graceful fallback to linear scan

Installation

This package ships a dsh.bundle manifest, so it can be installed as a regular profile bundle.

As a DSH Plugin

Add the plugin to your DSH profile (this runs pnpm add in the profile directory, so a git URL works):
```
dsh plugin --profile <your-profile> add github:disc0nct/dsh-memory-plugin
```

{
  "dependencies": {
    "@deepseek-ai/dsh-tool-memory": "github:disc0nct/dsh-memory-plugin"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@deepseek-ai/dsh-tool-memory"
      ]
    }
  }
}

Boot the profile:
```
dsh --profile <your-profile>
```

Usage

Available Tools

Once installed, the following tools become available to your DSH agent:

`memory_store`

Save an important fact to long-term memory.

// Store a user preference
await ctx.tools.memory_store({
  key: "user-name",
  value: "Alice",
  category: "preferences"
});

// Store project information
await ctx.tools.memory_store({
  key: "project-language",
  value: "TypeScript",
  category: "project"
});

// Store a decision
await ctx.tools.memory_store({
  key: "api-decision",
  value: "Use REST API for simplicity",
  category: "decisions"
});

`memory_search`

Search for memories by keyword, category, or semantic paraphrase (hybrid keyword+token Jaccard ranking, dependency-free).

// Search all memories
const results = await ctx.tools.memory_search({
  query: "Alice"
});

// Search by category
const results = await ctx.tools.memory_search({
  category: "preferences"
});

// Combined search
const results = await ctx.tools.memory_search({
  query: "API",
  category: "decisions",
  limit: 5
});

// Semantic paraphrase: "fav color" matches "favorite-color"
const results = await ctx.tools.memory_search({
  query: "fav color",
  mode: "hybrid" // | "keyword" | "semantic" (default: "hybrid")
});

// Force exact substring only
const results = await ctx.tools.memory_search({
  query: "color",
  mode: "keyword"
});

`memory_get`

Fast exact lookup by key (vs memory_search scan).

const { found, fact } = await ctx.tools.memory_get({ key: "user-name" });
if (found) console.log(fact.value);

`memory_list`

List all stored memories (most recent first, optionally filtered).

// List all memories
const memories = await ctx.tools.memory_list();

// List memories by category
const memories = await ctx.tools.memory_list({
  category: "project"
});

`memory_delete`

Delete a specific memory by its key.

await ctx.tools.memory_delete({
  key: "user-name"
});

`memory_clear`

Clear ALL stored memories (requires explicit confirmation).

// cancelled without confirm
await ctx.tools.memory_clear(); // { cleared:false, count: N }

// confirmed
await ctx.tools.memory_clear({ confirm: true }); // { cleared:true, count: N }

`memory_stats`

Get health stats (count, per-category, oldest/newest, file size).

const stats = await ctx.tools.memory_stats();
console.log(stats.count, stats.categories); // {count: 12, categories:{project:5}}

Memory Storage Format

Memories are stored in ~/.dsh/memory.json with this structure:

{
  "facts": [
    {
      "id": "unique-identifier",
      "key": "user-name",
      "value": "Alice",
      "category": "preferences",
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Configuration

- id: tool-memory
  config:
    memoryPath: /absolute/path/to/memory.json

Examples

Remembering User Information

// When user introduces themselves
if (userMessage.includes("my name is")) {
  const name = extractName(userMessage);
  await ctx.tools.memory_store({
    key: "user-name",
    value: name,
    category: "identity"
  });
}

// Later, when needing to address the user
const memory = await ctx.tools.memory_search({
  query: "name",
  category: "identity"
});
if (memory.results.length > 0) {
  await ctx.tools.memory_store({
    key: "greeting-used",
    value: `Hello ${memory.results[0].value}!`,
    category: "interaction"
  });
}

Project Context Tracking

// When starting work on a project
await ctx.tools.memory_store({
  key: "project-start",
  value: `Started work on ${projectName} at ${new Date().toISOString()}`,
  category: "project"
});

// When making a technical decision
await ctx.tools.memory_store({
  key: "tech-decision-db",
  value: "Selected PostgreSQL for reliability",
  category: "decisions"
});

// Later, when continuing work
const projectInfo = await ctx.tools.memory_list({
  category: "project"
});

How It Works

The plugin implements persistent memory by:

File Storage: Atomic writeFile(tmp)+rename to ~/.dsh/memory.json (no double-write), mkdir -p, max 5000 facts, orphan *.tmp.* sweep (>1h) via readdir on load
Concurrency: Per-file withWriteLock Promise queue (lib/storage.js:47-62) serializes store/delete/clear load→mutate→save — prevents lost updates; reads remain isConcurrencySafe
Timestamps: timestamp (ISO) + timestampMs (numeric, Date.now()) generated internally; compareRecent prefers timestampMs (no Date.parse per compare); old files migrated on load (backfill timestampMs via Date.parse)
Performance: mtime+size cache (lib/storage.js:105-115), inverted index Map<token,Set<id>> + Map<id,{hash,tokens}> cache (lib/search/scoring.js:50-120) — hybridSearch union of id sets → sub-linear, fallback linear on miss
Efficient Lookups: Hybrid search token Jaccard + substring boosts then timestampMs desc; empty query → recency
Upsert: memory_store replaces existing key and moves to most-recent
Validation: key/category kebab-case, value ≤10000, category ≤32, timestampMs 0..4102444800000 (lib/validation.js:5-27), MemoryPluginError + 3× retry for transient EACCES/EBUSY
Recovery: SyntaxError → *.corrupt.* backup + empty; ENOENT → empty; graceful degradation index→linear
Modular Layout: lib/config.js, lib/storage.js, lib/validation.js, lib/search/scoring.js, lib/tools/* (DSH apply re-exports)
DSH Idioms: Config via schemastery, defineTool timeoutMs:5000 isConcurrencySafe hints

Requirements

DeepSeek Harness (DSH) v0.1.0-rc.8 or later
Node.js v18.0.0 or later (uses crypto.randomUUID, fs/promises.rename/stat)
Peer dependencies:
- @deepseek-ai/cordis: ^4.0.1
- @deepseek-ai/dsh-tools: ^0.1.0-rc.8
- @deepseek-ai/schemastery: ^3.18.1

License

MIT License - feel free to use, modify, and distribute this plugin.

Development

To contribute to this plugin:

Fork the repository
Create a feature branch
Make your changes
Ensure all tests pass (if applicable)
Submit a pull request

Credits

Inspired by the memory systems in agents like Hermes AI, this plugin brings similar long-term memory capabilities to the DeepSeek Harness ecosystem.

Built with ❤️ for the DSH community

Tool Memory

兼容性与来源证明

版本

相关插件

Tool Memory

README

@deepseek-ai/dsh-tool-memory

Features

Installation

As a DSH Plugin

Usage

Available Tools

memory_store

memory_search

memory_get

memory_list

memory_delete

memory_clear

memory_stats

Memory Storage Format

Configuration

Examples

Remembering User Information

Project Context Tracking

How It Works

Requirements

License

Development

Credits

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

@deepseek-ai/dsh-tool-memory

Features

Installation

As a DSH Plugin

Usage

Available Tools

memory_store

memory_search

memory_get

memory_list

memory_delete

memory_clear

memory_stats

Memory Storage Format

Configuration

Examples

Remembering User Information

Project Context Tracking

How It Works

Requirements

License

Development

Credits

`memory_store`

`memory_search`

`memory_get`

`memory_list`

`memory_delete`

`memory_clear`

`memory_stats`

`memory_store`

`memory_search`

`memory_get`

`memory_list`

`memory_delete`

`memory_clear`

`memory_stats`