# ai-mate Core

Portable, read-only context and memory for MCP-compatible agents.

一个从个人 AI 应用中抽取的独立上下文内核：让不同 Agent 通过同一组接口，
读取显式指定的人格、长期记忆、当日摘要和接续卡，而不必接入原应用。

**当前为早期版本。它是上下文与记忆读取组件，不是完整 Agent 框架，
也不保证更换模型后会得到完全相同的人格表现。**

## 为什么做这个项目

对话入口、模型运行和记忆存储如果绑在一起，更换入口就容易变成重新维护一套系统。
本项目尝试把可共享的读取能力抽出来，同时把“读资料”和“修改资料”分开。

设计重点：

- 同一份 Core 服务不同入口，入口自行负责模型运行、工具执行和交互界面。
- 上下文读取不顺便初始化数据库、提炼记忆、刷新索引或推进其他功能状态。
- 返回有来源编号、范围检查和输出限制的上下文；读原文时再次检查资格。
- 人格和个人数据由使用者明确提供，不内置某个人的资料。

## 当前包含什么

| 资料 | 当前能力 |
| --- | --- |
| 人格 | 读取指定 Markdown 文件，返回其内容和版本标识 |
| 长期记忆 | 读取 SQLite 中符合条件的记录，关键词检索、来源追溯；可选本地语义检索 |
| Today | 按日期读取内部日摘要；不是待办、计划或日历界面 |
| 接续卡 | 显式开启后读取仍有效的近期话题；不会自动跨入口同步对话 |
| 离线准备 | 初始化空数据集，或导入明确选择的 JSON 数据到新目录 |

三个 MCP 工具：

| 工具 | 用途 |
| --- | --- |
| `core_get_context` | 装配人格、Today、有效接续卡及相关普通记忆；空查询只读锚点 |
| `core_recall` | 按主题检索符合条件的普通记忆 |
| `core_read_source` | 用返回的 `memory:N` 编号读取有限长度原文，并重新校验记录资格 |

不包含模型生成、多步 Agent 调度、自动记忆写入、日记、完整聊天档案、
世界书、工坊、网页界面或托管账号服务。私密分类和不合资格的反思记录不会
由这三个工具返回。普通分类也不代表可以公开转发。

## 快速开始：只用虚构资料

需要 Node.js **22.16+** 和 npm。已在 Windows / Node.js 24.14 上验证；
不据此承诺所有平台或最低版本均已实测。

```sh
git clone https://github.com/JH-builds/ai-mate-core.git
cd ai-mate-core
npm ci
npm run build
npm test
```

`npm test` 仅运行本仓库的独立 Core 合同，使用虚构资料和真实 stdio MCP，
不会连接私人服务或付费模型。安装不会下载嵌入模型。

先把随包示例导入一个**不存在的新目录**：

```sh
node dist/core/core-data.mjs import --data-dir ./demo-data --from ./dist/core/example-import.json
```

然后由支持 stdio MCP 的客户端启动：

```sh
node dist/core/core.mjs --data-dir ./demo-data --identity-file ./dist/core/example-identity.md
```

在客户端里配置时，使用 `core.mjs`、数据目录和人格文件的**绝对路径**。
上面的命令在终端中会等待 MCP 协议消息，不会打开网页；这是预期行为。
示例中的日期是固定的，不会冒充今天的新摘要或刷新已过期接续卡。

开启接续卡时追加 `--continuation`。创建空数据集则改用：

```sh
node dist/core/core-data.mjs init --data-dir ./empty-data
```

对于同一个新目录，`init` 和 `import` 二选一；已有目录不会被覆盖。
离线准备工具不属于 MCP 工具，模型不能通过这三个读取工具写入数据。

## 边界与数据安全

- 默认仅使用关键词检索；本地向量能力需另外安装依赖、提供兼容模型和已有索引。
- 本地进程权限是信任边界。允许某个客户端启动 Core，就意味着它能读到
  你指定范围内的资料；这里没有账号、项目或会话认证。
- 人格文件会完整提供给客户端，不会替你自动脱敏。首次连接请只用虚构示例。
- 不读取 `.env`，不隐式回退到原应用的人格和数据路径。
- 不要用未经认证的网络转发把这个 stdio 服务直接暴露到公网。
- SQLite 只读访问仍可能产生 WAL/共享内存协调文件；“只读”指无业务写入或迁移。
- 真实人格、导入文件和数据库建议放在仓库之外；`.gitignore` 只是辅助措施。

详细参数、JSON 导入格式和数据语义见
[运行与导入说明](scripts/core-mcp/standalone-README.md)。

## 源码与验证

这是从 ai-mate 中抽取的独立源码快照，公开仓库没有携带原应用的 Git 历史、
真实人格、记忆、环境配置或运行日志。`SOURCE-MANIFEST.json` 列出交付文件和存储方言。
交付时统一生成中性的 `private` 分类、类型和表名，不修改原应用数据库，
也不维护第二套检索实现。跨版本或从应用迁入时，请按导入格式显式映射分类，
不要直接挂载另一种存储方言的数据库；未知分类不会自动降为普通记录。

依赖由独立 `package-lock.json` 固定，使用 `npm ci` 安装。
`npm run build` 生成可搬移的 `dist/core` 运行包，其中附带完整第三方许可声明。
源码和测试重点覆盖：显式数据来源、导入保真、记录资格、来源复核、
数据库不被业务写回，以及不依赖网页服务的实际 MCP 调用。

## License

[MIT](LICENSE) · Copyright (c) 2026 JH-builds.

MIT 许可适用于本仓库交付的 Core 源码和文档，不代表原 ai-mate 应用或任何
未交付的私人内容一并公开。第三方依赖仍遵守各自许可；
分发构建后的运行包时，请一并保留 `LICENSE` 与 `THIRD-PARTY-NOTICES.txt`。
可选推理依赖和模型权重不随包分发，需另行遵守对应条款。