---
name: xmemory-setup
description: "设置用户级 XMemory 集中记忆库、登记项目和只读来源、检查配置、提供读取协议和定时提示词，或接入已有资料时使用。各客户端使用同一逻辑记忆库，跨设备通过用户配置的同步方式保持一致；只修改明确要求的设置，不用于普通记忆记录、查历史或客户端插件安装。"
---

# XMemory 设置

建立并维护多个客户端、多台机器共用的记忆库。设置不是采集，不因登记来源而读取其中的会话或记忆正文。

## 开始

读取 [共同约定](./references/contract.md)。初始化或改配置时读 [文件格式](./references/storage.md)；接入已有资料时读 [研究 demo 与已有资料](./docs/existing-data.md)。相对路径以本 SKILL.md 所在目录为基准。

默认记忆根为用户主目录下的 `~/.agents/memory/`，与当前工作区无关；用户明确路径或已有明确配置可以覆盖默认值。同一台机器上的客户端共用该用户的记忆根。多台机器使用同一逻辑记忆库，各机器默认位置为 `~/.agents/memory/`，通过用户选择的同步方式保持内容一致。不在项目中自动创建数据根或软链接；宿主不能访问集中库时如实说明，不回退到项目内另建副本。

## 按请求执行

### 检查设置

只读 `config.toml`、入口和用户点名的范围，检查格式、项目身份线索、来源路径在本机是否存在、链接和维护主体。报告具体问题，不自动初始化或修复，不遍历来源正文。来源只在别的机器上存在是正常情况，只说明“本机没有”，不判定配置错误。

### 初始化

1. 检查目标路径是否存在及其内容。不存在或为空时可继续；已有有效 XMemory 配置则保留并按增量设置处理；有其他内容或格式未知时停止，说明归属冲突。
2. 按 [配置模板](./templates/config.toml) 创建 `config.toml`，只填实际确认的项目和来源；不用示例身份替代用户项目。项目名明确时可建议一个小写连字符 ID；同名目录不能自动合并。
3. 按 [入口模板](./templates/MEMORY.md) 创建根 `MEMORY.md`，只列实际存在的入口。明确登记自管项目时创建其项目入口，创建后的 ID 保持稳定。
4. 不预建近况、记忆、事件文件、当日文件、积压和空目录；它们在有内容时产生。不扫描历史，不修改原生客户端数据，不创建任务或 Hook。
5. 回报记忆根、项目 ID 和写入边界，并说明接下来可做的三件事：把读取协议放进客户端规则、在项目根写项目 ID、需要时挂定时提示词。

### 登记与变更

先读现有配置，只改点名部分。项目身份用 ID；`repo`（Git 远程地址）和 `paths`（候选位置列表）都是可选的识别线索，不区分机器，也不登记设备。规范化路径并按目录边界比较；同一路径或远程地址归属不同 ID 时，先消除冲突。之后新登记的自管项目只新建其项目入口，根入口的项目列表由下次整理补上；设置除配置外不改已有文件。

来源需要路径或地址、所属范围和用途；`enabled = false` 的来源不读取。会话来源还需已有可用的只读工具或导出说明，未知数据库不作为文件格式自行解析。

已有 Office Memory 或其他独立维护者使用 `owner = "external"`，登记其入口，不新建第二套项目正文。改变 owner 不等于授权迁移或复制。

### 接入客户端

设置不自动编辑 `AGENTS.md`、`CLAUDE.md` 或其他客户端规则。用户明确要求接入时：

1. 先找出实际生效的规则文件，检查是否已有 XMemory 段落或 override，不覆盖旧规则。
2. 合并 [读取协议](./integrations/entry.md)；数据根不同则替换为实际路径。
3. 在项目根规则文件写一行“XMemory 项目 ID：<id>”，只写用户确认过的 ID。
4. 需要定时整理时，按 [定时提示词](./integrations/scheduled-curate.md) 填好项目、来源和同步命令，交给用户挂到客户端的定时任务上；不替用户创建任务。

## 完成检查

配置可解析、ID 唯一、项目识别线索无歧义；每个入口指向真实目标；没有示例占位内容被当成事实；没有触碰既有来源。没有解析工具时说明仅做人工结构检查，不声称 TOML 校验通过。

纯技能不提供系统级锁、权限隔离、同步或自动调度。不要把成功初始化报告为“已自动记忆”。