a_memorix-deepseek-harness

English

这是一个独立于 DeepSeek Harness 主仓库的扩展包。它从 DSH 的设置与凭据服务读取配置，启动固定 Namespace 的 A_memorix MCP 子进程，将记忆工具注册为 mcp__a-memorix__*，并向模型追加长期记忆使用规则。

用户配置只保存在两个 DSH 文件中：普通参数位于 $DSH_HOME/settings.yaml，密钥位于 $DSH_HOME/.credentials.yaml。适配器不要求用户设置 A_MEMORIX_* 环境变量，也不会读取项目或用户 .env 中的 Provider 密钥。

环境要求

• DeepSeek Harness 0.1.0-rc.6 或兼容版本
• Node.js ^22.19.0 或 >=24.0.0
• Python 3.12 或更高版本
• pnpm 已加入 PATH，供 dsh plugin 管理 profile 依赖
• A_memorix >=2.0.0a4,<3.0，并安装 mcp、vector extra

$DSH_HOME 默认是 macOS、Linux 的 ~/.dsh，以及 Windows 的 %USERPROFILE%\.dsh。

安装

下面以 web profile 为例。无界面 Agent 应把命令中的 web 换成 headless。

1. 安装 A_memorix

标准功能依赖 MCP、Faiss 向量检索和 Provider 客户端：

python -m pip install "a-memorix[mcp,vector]>=2.0.0a4,<3.0"
a-memorix --version

2. 安装插件

当前公开版本处于 alpha 阶段，请显式使用 npm 的 alpha 渠道：

dsh plugin --profile web add a-memorix-deepseek-harness@alpha

每个需要记忆能力的 profile 都要单独安装：

dsh plugin --profile headless add a-memorix-deepseek-harness@alpha

3. 写入普通配置

在 $DSH_HOME/settings.yaml 中增加 a-memorix 分节。标准模式至少需要配置 Embedding、LLM 的地址、模型和实际向量维度：

a-memorix:
  command: a-memorix
  namespace: deepseek-harness
  embedding:
    endpoint: https://provider.example/v1
    model: embedding-model
    credentialRef: A_MEMORIX_EMBEDDING_API_KEY
    dimension: 1024
  llm:
    endpoint: https://provider.example/v1
    model: chat-model
    credentialRef: A_MEMORIX_LLM_API_KEY

dimension 必须与 Embedding 服务实际返回的维度一致。如果 a-memorix 不在 PATH，把 command 改为可执行文件的绝对路径。无需设置 dataDir，默认数据目录为 $DSH_HOME/a-memorix。

4. 写入密钥

在 $DSH_HOME/.credentials.yaml 中使用设置文件里的凭据引用保存密钥：

A_MEMORIX_EMBEDDING_API_KEY: "embedding-secret"
A_MEMORIX_LLM_API_KEY: "llm-secret"

适配器通过 DSH Credentials 服务读取这些值。来自启动环境、项目 .env 或 $DSH_HOME/.env 的同名值会被拒绝，避免文件配置被不可见的外部状态覆盖。无需认证的本地 Provider 可以在 settings.yaml 中把对应的 credentialRef 设为空字符串，并从 .credentials.yaml 删除该条目。

5. 验证并启动

检查组合配置中是否包含 a-memorix-runtime 和 a-memorix-guidance：

dsh --profile web --dump-config
dsh --profile web

启动时会生成 $DSH_HOME/a-memorix/dsh.generated.toml。该文件不含密钥，只是 settings.yaml 的 A_memorix 运行时投影，不应手工编辑。设置与凭据修改后需要重启 DSH。

找不到命令、配置不完整、凭据来源错误、Provider 探测失败、向量池不可用或首次 MCP 工具发现失败时，profile 会直接报告错误，不会在缺少标准记忆能力的状态下静默运行。

配置说明

a-memorix 设置分节支持以下字段组，未填写的字段采用 schema 默认值：

字段组	主要字段	默认行为
根设置	command、namespace、dataDir	a-memorix、deepseek-harness、$DSH_HOME/a-memorix
mcp	mode、probeLlm	standard、启动时探测 LLM
embedding	endpoint、model、credentialRef、dimension、dimensionRequestMode、batchSize、maxConcurrent、timeoutSeconds	OpenAI 兼容接口、1024维、并发5、超时60秒
embedding.retry	maxAttempts、delaySeconds、maxDelaySeconds、backoffMultiplier	3次、1秒、20秒、2倍退避
llm	endpoint、model、credentialRef、maxConcurrent、maxTokens、temperature、timeoutSeconds	OpenAI 兼容接口、并发3、8192 token、温度0、超时120秒
llm.retry	与 Embedding 相同	3次、1秒、20秒、2倍退避
llm 思考参数	thinkingProtocol、thinkingEnabled	provider-default，不发送扩展字段
observability	logLevel、logFormat、accessLog、serviceName、metricsHost、metricsPort、otlpEndpoint、otlpInsecure、traceSampleRatio	JSON INFO 日志，指标与 OTLP 默认不启用
connection	toolCallTimeoutMs、reconnect.enabled、initialDelayMs、maxDelayMs、maxAttempts	调用超时60秒，自动重连，最多10次

thinkingProtocol 可取 provider-default、enable-thinking、thinking-mode。后两种协议使用 thinkingEnabled 决定开关状态。

只有明确接受能力缺失时才把 mcp.mode 设为 degraded。标准模式要求元数据、稀疏索引、图存储、Embedding、LLM、段落向量池和关系向量池全部就绪。

每个适配器实例始终绑定一个 Namespace。需要隔离时应使用另一个 DSH profile，并在该 profile 对应的设置中指定不同 Namespace，不能通过模型工具参数动态切换。

更新与卸载

重新执行安装命令即可更新指定 profile：

dsh plugin --profile web add a-memorix-deepseek-harness@alpha

卸载插件：

dsh plugin --profile web remove a-memorix-deepseek-harness

卸载只移除 profile 依赖和配置层，不会删除 $DSH_HOME/settings.yaml 中的设置、.credentials.yaml 中的密钥或 $DSH_HOME/a-memorix 中的记忆数据。

可用功能

固定 Namespace MCP 服务提供单条写入、批量写入、混合及语义检索、直接读取、按记忆删除、按来源创建删除任务、查询任务和 Namespace 健康检查。标准写入同步维护元数据、稀疏索引、段落向量、实体关系图和关系向量；删除会清理这些存储中的对应数据。

当前版本由模型根据工具描述和提示规则决定何时检索、写入，不会静默归档每一条会话消息。确定性的自动召回、自动归档需要接入 Harness 的持久化会话事件，后续将作为独立策略层提供。

许可证

适配器 bundle 使用 MIT 许可证。A_memorix 作为独立软件按 AGPL-3.0-only 分发，DeepSeek Harness 按其自身许可证独立分发。