MemoraX Code 在多仓库开发中的记忆隔离配置

当多个代码仓库共用同一个 MemoraX Code 实例时，默认的记忆存储通常按实例级目录或全局工作区组织，不会自动区分仓库。结果是仓库 A 积累的上下文判断会出现在仓库 B 的回复建议里，形成记忆污染。要解决这个问题，需要把记忆的作用域从“整个实例”收窄到“单个仓库”，具体做法是为每个仓库分配独立命名空间，并在配置和调用链路上都带上仓库标识。

记忆隔离的关键是让仓库标识贯穿存储与请求两个环节：在 MemoraX Code 配置文件中设置 project_key 和 namespace 固定仓库身份；在调用 API 时通过公共头或查询参数传入同一标识；验证时分别写入不同记忆再交叉查询；仓库迁移时需先导出旧命名空间内存数据，再导入到新命名空间并与实际项目比对。此方案适用于多仓库共用实例但需要各自独立上下文的场景，具体配置项名称需结合当前版本确认。

理解 MemoraX Code 的默认记忆作用域

MemoraX Code 默认情况下会把记忆写入实例级的存储目录，通常位于数据目录下的 memory 或 index 子目录，内部按对话时间或哈希键保存，而不会自动读取当前代码仓库的标识。这意味着只要两个仓库用的是同一套 MemoraX Code 启动参数，它们读取和写入的都是同一份记忆空间。

这种设计的优势是无需配置即可使用，但代价是作用域颗粒度太大。仓库 A 里关于“订单模块用 Python 重写”的长期记忆，会被仓库 B 的问答命中并带进建议里。即使 MemoraX Code 在内部对记忆做了向量化或关键词索引，隔离依然不会自动发生——根因是存储路径和查询范围都没有按仓库维度做切分。

因此，第一步是确认当前实例的记忆目录结构。通常可以在 MemoraX Code 启动日志里看到 memory path 或 storage dir 字段，如果该路径是全局共享的，就说明存在记忆串扰风险。

为每个仓库设置独立命名空间

要让记忆按仓库隔离，最直接的方式是在 MemoraX Code 的配置文件中显式声明仓库身份。配置文件一般是项目根目录下的 memora.config.json 或 .memora.yaml，建议将以下字段作为必填项：

{
  "project_key": "repo-order-service",
  "namespace": "order-service-prod",
  "storage": {
    "base_dir": "./memora_data"
  }
}

project_key 是仓库的短期标识，用于在日志和命名空间目录中快速定位；namespace 是记忆隔离的真正边界，建议使用“业务名-环境”的命名风格，例如 payment-api-staging。配置完成后，MemoraX Code 通常会在 base_dir 下创建以 namespace 命名的子目录，所有长期记忆都会写入该目录，查询时也只检索该目录。

需要说明的是，project_key 与 namespace 的划分方式不是所有版本都一致。如果当前版本不支持两个字段，可以先只设置 namespace，并将 project_key 放入 description 或 tags 字段中，等升级后再拆分。重点在于每个仓库都必须有一个唯一且固定的 namespace，不能使用随机字符串，否则重启后无法复现同一仓库的上下文。

在调用 API 时传入仓库上下文

配置文件只在启动或首次加载时生效。如果 MemoraX Code 以服务模式运行，多个仓库的请求会通过 HTTP 或 SDK 发给同一个后端进程，后端无法自行判断请求来自哪个仓库。因此运行时请求也必须携带仓库标识。

以下是一个通用 API 接入骨架，可在网关层或 SDK 客户端统一注入公共请求头：

PUT /v1/memories  HTTP/1.1
Host: memora.internal
Content-Type: application/json
X-Memora-Project-Key: repo-order-service
X-Memora-Namespace: order-service-prod

{
  "type": "long_term",
  "content": "订单模块的结算逻辑统一走优惠券服务"
}

查询时使用同一组请求头：

GET /v1/memories/query?q=结算逻辑
X-Memora-Project-Key: repo-order-service
X-Memora-Namespace: order-service-prod

如果 MemoraX Code 提供的是 SDK 而不是 REST 接口，通常可以在 Client 初始化的 options 里设置 default_headers，或直接在请求对象的 params 中加入 namespace 字段。无论走哪种方式，关键规则是：配置文件里的 namespace 与 API 请求里的 namespace 必须完全一致，建议把两者放到同一个版本管理文件里，避免仓库配置更新后运行时仍发送旧标识。

验证不同仓库的记忆互不影响

配置完成后，需要主动验证隔离是否生效，而不是只看进程能启动。推荐采用“写入-交叉查询”的验证方式，分三步执行。

第一步，在仓库 A 的命名空间下写入一条带独特关键词的记忆：

curl -X PUT http://127.0.0.1:8787/v1/memories \
  -H "X-Memora-Namespace: repo-a" \
  -H "Content-Type: application/json" \
  -d '{"content":"仓库A专属凭证：订单支付成功后返回 status=PAID"}'

第二步，在仓库 B 的命名空间下查询同一关键词：

curl "http://127.0.0.1:8787/v1/memories/query?q=status=PAID" \
  -H "X-Memora-Namespace: repo-b"

期望的返回结果是空列表或无相关记忆。如果仓库 B 的查询结果里出现了仓库 A 写入的内容，说明命名空间没有生效。

第三步，检查日志输出。MemoraX Code 在处理每个请求时通常会打印命中记忆的文件路径或索引 ID，例如 hit memory: memora_data/repo-a/2025-05-01.md。日志里路径中的命名空间部分必须与请求头一致。如果日志显示路径是全局目录，则说明服务端没有读取传入的命名空间，需要检查请求头名称是否拼写正确。

还有一种常见的假阳性情况：仓库 B 的查询结果为空，但日志显示仍然扫了所有目录。这可能是内存缓存未清理，建议在验证前重启 MemoraX Code 服务，或调用缓存清理接口让查询走真实存储。

处理迁移仓库时的历史记忆归属

仓库迁移或项目改名后，旧 namespace 下的长期记忆不会自动跟随。若直接修改仓库配置中的 namespace，之前积累的上下文相当于被丢弃，这会让 MemoraX Code 的回复质量明显下降。处理思路是保留旧 namespace 的数据，并在新 namespace 中重建索引。

MemoraX Code 通常提供导出与导入命令。如果当前版本支持 CLI，可以这样操作：

memora export `--namespace` order-service-prod `--output` ./backup/order-service-prod.json

然后在仓库的新配置中启用新命名空间，再执行导入：

memora import `--namespace` order-service-v2 `--input` ./backup/order-service-prod.json

如果不提供 import 命令，可以直接将旧 namespace 目录下的记忆文件复制到新目录，但文件名中的时间戳与哈希值可能冲突，通常建议先备份并在测试环境中验证一遍再复制。

迁移完成后，用仓库中的典型问题重新查询，检查返回内容是否包含旧记忆里的核心关键词。同时对比旧 namespace 导出文件与新 namespace 导入文件的行数或对象数量，确认没有遗漏。需要留意的是，迁移后的记忆会以新 namespace 为基准继续增量写入，旧 namespace 建议保留一段时间再清理，以免回滚时需要恢复。

以上所有配置项和命令的具体名称，应以实际环境中的 MemoraX Code 版本说明为准。确认版本支持后，再按这里给出的顺序逐步实施。