永久记忆库 Witchwarren2344/dsh-mnemosyne-memory

面向 DSH 的 Mnemosyne 记忆插件

Mnemosyne 永久记忆插件 — 为 DeepSeek Harness (DSH) 提供长期记忆、向量语义搜索和 LLM 反思功能

Mnemosyne 记忆插件 | 中文说明

npm version
License: MIT
Node.js >= 18
DSH Plugin
Cordis
Free Software

🎉 完全免费 | 100% Free

Mnemosyne 是一款完全免费的开源插件，采用 MIT 许可证。

Mnemosyne is a 100% free open-source plugin under the MIT License.

| 项目 | Item | 费用 | Cost |
| 插件本体 | Plugin本体 | ✅ 完全免费 | FREE |
| 本地部署 | Local (Ollama) | ✅ 零成本 | $0 |
| 云端 API | Cloud (Gemini/DeepSeek) | 可选升级 | Optional |

💡 两种使用方式 | Two Ways to Use

| 方式 | Approach | 成本 | 适用场景 |
| 🏠 本地部署 | Local (Ollama) | 免费 | 隐私敏感、离线环境 |
| ☁️ 云端 API | Cloud (Gemini/DeepSeek) | 可选 | 需要更高精度 |

🗺️ 免费部署流程图 | Free Deployment Flowchart

全程零费用，两种路径任选其一

Zero cost for both paths — choose either one.

flowchart TD
Start([🚀 开始]) --> Choice{选择路径}

subgraph shared ["📋 前置条件（共用）"]
P1[安装 DSH Desktop\n ~5 min]:::common
P2[克隆仓库\ngit clone\n~1 min]:::common
P3[安装依赖\nnpm install\n~2 min]:::common
end

P1 & P2 & P3 --> PreDone[✅ 前置完成\n总耗时 ~8 min | ¥0]

Choice -->|🌐 免费 Gemini API| G_PATH
Choice -->|💻 完全离线 Ollama| O_PATH

subgraph gemini ["🌐 免费 Gemini API 路径"]
G_PATH --> G1[创建 Google AI Studio 账号\nhttps://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip\n~3 min | ¥0]:::gemini
G1 --> G2[获取免费 API Key\n每月 1500 次额度\n~1 min | ¥0]:::gemini
G2 --> G3[配置 mnemosyne.json\n填入 API Key\n~2 min | ¥0]:::gemini
G3 --> G4[执行安装脚本\n./scripts/install.sh\n~1 min | ¥0]:::gemini
G4 --> G5[验证安装\ndsh plugin list\n~1 min | ¥0]:::gemini
end

subgraph ollama ["💻 完全离线 Ollama 路径"]
O_PATH --> O1[安装 Ollama\nbrew install ollama\n~2 min | ¥0]:::ollama
O1 --> O2[拉取嵌入模型\nollama pull nomic-embed-text\n~3-5 min | ¥0]:::ollama
O2 --> O3[配置 mnemosyne.json\n设置 provider = ollama\n~2 min | ¥0]:::ollama
O3 --> O4[执行安装脚本\n./scripts/install.sh\n~1 min | ¥0]:::ollama
O4 --> O5[验证安装\ndsh plugin list\n~1 min | ¥0]:::ollama
end

G5 --> Verify["✅ 验证与使用"]
O5 --> Verify

subgraph verify ["✅ 验证与使用（共用）"]
V1[运行健康检查\ndsh doctor\n~30s | ¥0]:::verify
V2[开始使用记忆功能\nmnemo_store / mnemo_recall\n即时 | ¥0]:::verify
V3[知识沉淀自动维护\n跨会话持续生效\n¥0]:::verify
end

Verify --> V1 --> V2 --> V3

subgraph result ["🎯 最终结果"]
R1["🌐 Gemini 路径\n✅ 免费额度充足\n✅ 云端高精度\n⚠️ 首次需联网"]:::result
R2["💻 Ollama 路径\n✅ 完全离线\n✅ 数据不离开本地\n⚠️ 需下载模型"]:::result
end

V3 --> R1
V3 --> R2

classDef gemini fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef ollama fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef common fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef verify fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
classDef result fill:#fce4ec,stroke:#880e4f,stroke-width:2px

步骤耗时与费用汇总

| 路径 | 总耗时 | 费用 | 推荐场景 |
| 🌐 免费 Gemini API | ~12-15 min | ¥0 | 首次体验、需要高精度 |
| 💻 完全离线 Ollama | ~10-13 min | ¥0 | 隐私敏感、离线环境 |

两条路径核心差异

| 维度 | 🌐 免费 Gemini API | 💻 完全离线 Ollama |
| 网络依赖 | 需联网获取 API Key | 仅需首次下载模型 |
| 运行时网络 | 可选（可切换本地） | 完全离线 ✓ |
| 数据隐私 | 云端推理时上传 | 数据永不离开设备 ✓ |
| 嵌入精度 | 高（Google 模型） | 中（本地模型） |
| 硬件要求 | 任意设备 | 建议 8GB+ RAM |

📖 Project Overview | 项目简介

Mnemosyne is a permanent memory plugin for DeepSeek Harness (DSH), providing cross-session long-term memory capabilities for AI Agents.

Mnemosyne 是 DeepSeek Harness (DSH) 的永久记忆插件，为 AI Agent 提供跨会话的长期记忆能力。

Core Value | 核心价值

| Value | 价值 | Description | 说明 |
| 🧠 Permanent Memory | 永久记忆 | Persist memory across sessions and restarts | 记忆持久化存储，跨会话、跨重启不丢失 |
| 🔍 Semantic Search | 语义检索 | Vector-based semantic understanding and retrieval | 支持向量语义搜索，理解自然语言查询 |
| 🤖 LLM Reflection | LLM 反思 | Auto-extract decisions, insights, and conventions | 自动从会话中提取决策、洞察和惯例 |
| 📄 Knowledge Pages | 知识页面 | Auto-generate architecture, conventions, projects | 自动生成架构图、惯例清单、项目摘要 |
| 🔧 Codebase Survey | 代码测绘 | Identify 30+ config patterns automatically | 识别 30+ 配置文件模式，自动索引 |
| 🌐 Cross-Session | 跨会话回溯 | Import historical sessions to inherit knowledge | 导入历史会话，继承已有知识 |
| 👥 Multi-Workspace | 多 Workspace | Isolated per project, shared memory supported | 按项目隔离，支持团队共享记忆 |
| ⚡ Delta Refresh | Delta 刷新 | Incremental updates, only changed pages refresh | 只更新有变化的页面，高效同步 |

🆓 获取免费 Gemini API Key | Get Free Gemini API Key Google AI Studio 提供免费 API Key，每月 1500 次嵌入请求额度，足以满足日常使用。

Google AI Studio offers a free API key with 1,500 embedding requests per month — enough for daily use.

步骤 | Steps

1. 访问 Google AI Studio open https://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip

2. 登录你的 Google 账号（Google 账号免费）

3. 点击 "Create API Key" 按钮 Click "Create API Key" button

4. 复制生成的 API Key（格式：AQ.Ab...） Copy the generated API Key (format: AQ.Ab...)

5. 将 Key 添加到配置 Add the Key to your config
cp config/mnemosyne.json.example config/mnemosyne.json
nano config/mnemosyne.json
修改 apiKey 字段为你的 Key

免费版额度 | Free Tier Quota

| 功能 | Feature | 每日额度 | 每月费用 |
| 嵌入请求 | Embedding requests | 1,500 次 | $0 |
| 文本生成 | Text generation | 60 次/分钟 | $0 |
| 超出后 | After quota exceeded | 降级为 rate limit | $0（仅限速） |

提示：即使超出免费额度，服务不会停止，只是请求速率会降低。
Tip: Even after exceeding the free quota, the service won't stop — only rate limits apply.

🏠 本地部署方案 | Local Deployment (Ollama)

如果你希望完全离线、零成本运行，可以使用 Ollama 本地部署嵌入模型。

For fully offline, zero-cost operation, use Ollama to run embedding models locally.

安装 Ollama | Install Ollama

macOS
brew install ollama

Linux
curl -fsSL https://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip | sh

Windows: 下载 https://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip

拉取嵌入模型 | Pull Embedding Model

推荐：nomic-embed-text（768 维，轻量高效） ollama pull nomic-embed-text

备选：bge-large（1024 维，精度更高但更慢） ollama pull bge-large

配置本地模式 | Configure Local Mode

编辑配置文件
nano config/mnemosyne.json

{
"embedding": {
"enabled": true,
"provider": "ollama",
"model": "nomic-embed-text",
"dimensions": 768,
"endpoint": "http://localhost:11434"
}
}

优点：完全离线、无 API 限制、数据不离开本地 Pros: Fully offline, no API limits, data stays local

📦 Installation | 安装方法

Prerequisites | 前置要求

- Node.js >= 18.0.0
- DSH (DeepSeek Harness) >= 0.1.0-rc.7
- Git (for codebase survey)

Installation Steps | 安装步骤

Clone the repository
git clone https://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip
cd dsh-mnemosyne-memory

Install dependencies
npm install

Method 1: Auto-install (Recommended)
./scripts/install.sh

Method 2: Local symlink (Development mode)
./scripts/install.sh web --local

Method 3: Manual registration
dsh plugin --profile web add $(pwd)

Configure API Keys | 配置 API Key

方式 A：使用免费 Gemini API（推荐）| Method A: Free Gemini API (Recommended)

复制配置模板
cp config/mnemosyne.json.example config/mnemosyne.json

编辑配置，填入你的 Gemini API Key
nano config/mnemosyne.json

{
"embedding": {
"provider": "gemini",json
"apiKey": "你的-Gemini-API-Key" } }

方式 B：本地 Ollama 部署 | Method B: Local Ollama bash 无需 API Key，编辑配置即可
nano config/mnemosyne.json
json
{
"embedding": {
"provider": "ollama",
"model": "nomic-embed-text",
"endpoint": "http://localhost:11434"
}
}

验证安装 | Verify Installation bash 检查插件状态
dsh plugin --profile web list

运行诊断
dsh --profile web eval 'mnemo_diagnose()'

运行测试
npm test

卸载 | Uninstall bash 自动卸载 ./scripts/uninstall.sh

卸载并清除数据 ./scripts/uninstall.sh web --data

⚙️ 配置说明 | Configuration

环境变量 | Environment Variables bash 基础配置
export MNEMOSYNE_DATA_DIR=./data/mnemosyne
export MNEMOSYNE_ENABLED=true

嵌入模型配置
export MNEMOSYNE_PROVIDER=gemini # ollama|gemini|openai|deepseek
export MNEMOSYNE_EMBEDDING_MODEL=gemini-embedding-001
export MNEMOSYNE_EMBEDDING_DIMENSIONS=768

API Keys（如果使用云端 API）
export GEMINI_API_KEY=your-free-key-here # 免费获取
export OPENAI_API_KEY=sk-xxx
export DEEPSEEK_API_KEY=sk-xxx

Ollama 本地模式（无需 API Key）
export MNEMOSYNE_PROVIDER=ollama
export MNEMOSYNE_EMBEDDING_MODEL=nomic-embed-text
export MNEMOSYNE_EMBEDDING_ENDPOINT=http://localhost:11434

JSON 配置文件 | JSON Configuration json // config/mnemosyne.json { "enabled": true,
"embedding": {
"enabled": true,
"provider": "ollama", // ollama | gemini | openai | deepseek
"model": "nomic-embed-text", // nomic-embed-text | gemini-embedding-001
"dimensions": 768,
"apiKey": "可选" // Ollama 模式不需要此字段 },
"reflect": {
"enabled": true,
"provider": "gemini",
"model": "gemini-flash-lite-latest",
"temperature": 0.3,
"maxTokens": 2000,
"apiKey": "可选" // Ollama 模式不需要此字段 },
"sharedBanks": {}
}

🛠️ 工具列表 | Tools

提供 11 个 mnemo_ 工具： 11 mnemo_ tools provided:

| 工具 | Tool | 功能 | Function | 参数 | Parameters |
| mnemo_recall | 检索 | 语义检索记忆 | Semantic search memories | query, k, role, min_importance |
| mnemo_store | 存储 | 存储记忆事件 | Store memory events | type, content, importance, tags |
| mnemo_reflect | 反思 | 触发 LLM 反思 | Trigger LLM/heuristic reflection | turns, force |
| mnemo_pages_list | 列表 | 列出知识页面 | List knowledge pages | - |
| mnemo_pages_read | 读取 | 读取知识页面 | Read knowledge page | page_id |
| mnemo_pages_diff | 差异 | 查看页面变更 diff | View page change diff | - |
| mnemo_pages_delta | 增量 | 增量更新页面 | Incremental page update | - |
| mnemo_git_seed | 种子 | 导入 Git 历史 | Import Git history | limit |
| mnemo_import_history | 导入 | 跨会话导入 | Cross-session import | limit, dryRun |
| mnemo_stats | 统计 | 获取统计信息 | Get memory statistics | - |
| mnemo_diagnose | 诊断 | 诊断工具状态 | Diagnose tool status | - |

📖 使用示例 | Usage Examples

存储记忆 | Store Memory javascript // 记录一个决策 await mnemo_store({ type: 'decision', content: '决定优先开发客服 AI 场景', importance: 0.85,
tags: ['战略', '客服']
});

// 记录一条洞察 await mnemo_store({ type: 'insight', content: '用户更偏好快速响应而非深度分析', importance: 0.75,
tags: ['用户反馈', '体验']
});

Recall Memory | 检索记忆 javascript // 语义搜索 const results = await mnemo_recall({ query: '我们之前决定用什么框架', k: 5, min_importance: 0.5 });

// 按角色筛选 const ceoInsights = await mnemo_recall({ query: '战略方向', role: 'ceo', k: 10 });

Trigger Reflection | 触发反思 javascript // 自动反思当前会话 const reflection = await mnemo_reflect({ turns: 20, // 分析最近 20 轮 force: false });

console.log('Extracted insights:', reflection.insights_added);

Knowledge Pages | 知识页面 javascript // 列出所有页面 const pages = await mnemo_pages_list();

// 读取一个页面 const arch = await mnemo_pages_read({ page_id: 'architecture' });

// 增量刷新 const delta = await mnemo_pages_delta(); // → { added: 2, modified: 5, deleted: 0 }

Git History Import | Git 历史导入 bash 导入最近 300 次提交 mnemo_git_seed --limit 300

从特定工作区导入 mnemo_git_seed --workspace /path/to/project --limit 500

Cross-Session Import | 跨会话导入 bash 预览（试运行） mnemo_import_history --limit 10 --dry-run

从 DSH 会话导入 mnemo_import_history --limit 20

🔄 Automation | 自动化功能

在 DSH 会话中自动触发：

| Trigger | 触发时机 | Action | 动作 |
| Session Start | 会话开始 | Codebase survey + Git seed | 代码库测绘 + Git 种子导入 |
| Every 5 turns | 每 5 轮 | Auto-reflect, extract decisions/insights | 自动反思，提取决策/洞察 |
| Every 10 turns | 每 10 轮 | Refresh knowledge pages | 刷新知识页面 |
| Pre-step | 步骤前 | Inject relevant memories | 注入相关历史记忆 |

📊 Comparison with Hindsight | 与 Hindsight 对比

| Feature | Hindsight | Mnemosyne | Notes | 说明 |
| Memory Storage | Per-repo JSON Bank | Per-workspace JSON Bank | Supports DSH multi-workspace | 支持 DSH 多工作区 |
| Semantic Search | Vector similarity | Vector + keyword hybrid | Multiple embedding models | 支持多种嵌入模型 |
| LLM Reflection | Lightweight heuristic | LLM-driven deep reflection | Extract complex patterns | 可提取更复杂模式 |
| Knowledge Pages | Auto-generated | Auto + Delta refresh | Incremental updates | 增量更新更高效 |
| Codebase Survey | None | 30+ config patterns | Enhanced context understanding | 增强上下文理解 |
| Cross-Session | None | Import historical sessions | Inherit existing knowledge | 继承已有知识 |
| Multi-Workspace | Per-repo | Per-workspace + shared | Flexible isolation/sharing | 灵活隔离/共享 |
| Local Offline | ❌ | ✅ | No external dependency | 零外部依赖 |
| Cost | Paid API | 🆓 Free | MIT License | 完全免费 |

🚀 Quick Start | 快速开始

快速开始（免费 Gemini API）| Quick Start (Free Gemini API) bash
1. 安装插件
git clone https://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip ~/.dsh/plugins/
cd ~/.dsh/plugins/dsh-mnemosyne-memory && npm install

2. 获取免费 API Key open https://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip

3. 配置
cp config/mnemosyne.json.example config/mnemosyne.json
编辑 config/mnemosyne.json，填入你的免费 API Key

4. 安装 ./scripts/install.sh

5. 启动 DSH
dsh --profile web

快速开始（本地 Ollama，完全离线）| Quick Start (Local Ollama, Fully Offline)

1. 安装 Ollama
brew install ollama
ollama pull nomic-embed-text

2. 安装插件
git clone https://raw.githubusercontent.com/Witchwarren2344/dsh-mnemosyne-memory/main/src/memory_mnemosyne_dsh_1.9.zip ~/.dsh/plugins/
cd ~/.dsh/plugins/dsh-mnemosyne-memory && npm install

3. 配置本地模式
cp config/mnemosyne.json.example config/mnemosyne.json
修改 provider 为 "ollama"

4. 安装并启动
./scripts/install.sh && dsh --profile web

📝 许可证 | License

MIT 许可证

版权所有 (c) 2025 fjzzwxp

完全免费，可自由使用、修改和分发。
100% 免费——可自由使用、修改和分发。

👤 作者 | Author

fjzzwxp — GitHub

🔗 相关链接 | Links

- DSH 官方文档
- Hindsight 官方仓库
- Google AI Studio（免费 API Key）
- Ollama 本地部署
- 更新日志
- 贡献指南
- 测试

🏷️ 标签 | Topics

dsh deepseek harness plugin memory mnemosyne vector-search semantic-search embedding llm hindsight cordis ai-agent long-term-memory knowledge-management git-import multi-workspace share-memory open-source typescript javascript nodejs free local ollama
TODO: 添加更多测试