内容
# AI 上下文中心
<p align="center">
<strong>Claude Code记住了它。Codex忘记了它。这解决了这个问题。</strong>
</p>
<p align="center">
<a href="https://github.com/huyuanjun/ai-context-hub/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
<a href="https://www.npmjs.com/package/ai-context-hub"><img alt="npm" src="https://img.shields.io/badge/npm-ai--context--hub-red.svg"></a>
<a href="https://github.com/huyuanjun/ai-context-hub/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/huyuanjun/ai-context-hub/actions/workflows/ci.yml/badge.svg"></a>
<a href="#"><img alt="Node" src="https://img.shields.io/badge/node-%3E%3D20-green.svg"></a>
<a href="#"><img alt="Dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen.svg"></a>
</p>
AI 上下文中心为每个AI编码工具提供了一个**单一、共享的长期记忆**。您教给Claude Code关于代码库的信息——Codex、Gemini、Cursor和Windsurf都自动知道它。无需重复自己。
- **零依赖** — 纯Node.js内置模块，无需安装任何东西
- **跨平台** — Windows、macOS、Linux
- **令牌高效** — 通过grep-first访问，每个查询约50个令牌；从不将整个图加载到上下文中
- **并发安全** — 文件锁定邮箱，原子写入；多个工具可以同时写入
---
## 演示
```bash
$ ai-context remember "Payment 模块使用 Stripe API v2，不使用 v1 回调" --entity payment --confidence 1.0
写入邮箱内存
$ ai-context remember "后端在 AWS us-east-1，RDS db.t3.xlarge" --entity infra
写入邮箱内存
$ ai-context sync
{ "scannedFiles": 2, "added": 2 }
$ ai-context search "Stripe"
{ "mode": "keyword", "results": [...], "count": 1 }
$ ai-context search "数据库配置" --semantic
{ "mode": "semantic", "results": [{ "text": "...RDS db.t3.xlarge", "score": 0.71 }] }
$ ai-context relate --from zhang-wei --to payment --kind works_on --apply
{ "status": "added", "relation": { "from": "zhang-wei", "to": "payment", "kind": "works_on" } }
```
自己运行：`bash demo/run.sh`
---
## 安装
```bash
npm install -g ai-context-hub
```
或从源代码运行（无需构建步骤）：
```bash
git clone https://github.com/huyuanjun/ai-context-hub.git
cd ai-context-hub
npm link # 或直接将 src/cli.js 放入 PATH 中
```
需要 Node.js >= 20。
---
## 快速入门
```bash
ai-context init # 创建 ~/.ai-context
ai-context scan # 检测现有的 AI 工具配置
ai-context import # 导入现有的引导 + 技能
ai-context enable --dry-run # 预览将要更改的内容
ai-context enable --apply # 将共享上下文部署到所有工具
```
覆盖数据目录：`ai-context init --root /custom/path` 或 `export AI_CONTEXT_ROOT=/custom/path`
---
## 工作原理
```mermaid
flowchart LR
A["🧠 remember<br/>将事实写入邮箱"] --> B["📥 inbox/<br/>每个事实一个文件"]
B --> C["🔄 sync<br/>合并 + 去重"]
C --> D["📝 canonical/<br/>markdown 事实"]
C --> E["🔗 memory.jsonl<br/>实体-观察图"]
D --> F["🔍 search<br/>关键词 + TF-IDF"]
E --> F
G["🤖 Claude Code"] -.->|读取引导| D
H["🤖 Codex"] -.->|读取引导| D
I["🤖 Gemini"] -.->|读取引导| D
J["🤖 Cursor"] -.->|读取引导| D
```
1. **`remember`** → 将每个事实写入 `inbox/` 的一个 JSONL 文件中 — 零写入冲突
2. **`sync`** → 加锁 → 去重（SHA256）→ 合并到规范 `.md` + 实体图
3. **AI 工具** → 通过引导文件使用 `grep`/`Select-String` 查找事实，从不加载整个图
4. **`search`** → 关键词（即时子字符串）或语义（TF-IDF + 余弦相似度）
---
## AI 工具支持
`ai-context enable --apply` 编写轻量级引导文件（约350个令牌每个）：
| 工具 | 引导文件 | 技能 |
|------|-----------|--------|
| Claude Code | `~/.claude/CLAUDE.md` | `~/.claude/skills/` |
| Codex | `~/.codex/AGENTS.md` | `~/.codex/skills/` |
| Gemini CLI | `~/.gemini/GEMINI.md` | — |
| Cursor | `.cursor/rules/shared-ai-context.mdc` | — |
| Windsurf | `.windsurf/rules/shared-ai-context.md` | — |
| 自定义代理 | `~/.agents/AGENTS.md` | `~/.agents/skills/` |
技能是符号链接的，因此一次创建的技能可以在Claude Code、Codex和Agents中同时使用。
---
## 数据布局
```text
~/.ai-context/
config.json ← 中心配置
memory/
inbox/ ← 暂存区：每个事实一个 JSONL 文件
claude/ codex/ manual/
canonical/ ← 合并的 markdown，每个实体一个文件
global.md ← AI 工具使用说明
preferences.md ← 用户约束
payment.md ← 每个实体的事实
graph/
memory.jsonl ← 实体-观察图
.search-index.json ← 缓存的 TF-IDF 索引
skills/ ← 共享技能（符号链接到每个工具）
backups/ ← 备份快照
logs/ ← 结构化 JSONL 日志
```
---
## 命令
| 命令 | 描述 |
|---------|-------------|
| `remember <fact>` | 将事实写入邮箱 |
| `sync` | 合并邮箱 → 规范 + 图 |
| `search <query>` | 关键词搜索（添加 `--semantic` 进行 TF-IDF） |
| `context` | AI 提示注入的紧凑上下文 |
| `relate --from X --to Y --kind K` | 创建实体关系 |
| `relations <entity>` | 查看实体的关系 |
| `remove-relation --id <id>` | 删除关系 |
| `list` | 列出所有实体 |
| `expire` | 存档 TTL 过期的观察 |
| `watch` | 连续同步 + 索引 + 验证循环 |
| `schedule` | 生成 OS 调度器脚本 |
| `skills validate/index` | 管理技能 |
| `link / adopt` | 将技能部署到 AI 工具 |
| `enable` | 完整部署：验证 → 索引 → 采用 → 链接 → 快照 |
| `snapshot / history / restore` | 中心状态的 Git 基础版本控制 |
| `backup create / list` | 备份快照 |
| `doctor` | 全系统健康检查 |
| `mcp` | 导出 MCP 配置片段 |
---
## 为什么不使用共享文件？
| 方法 | 多工具 | 关系 | 语义搜索 | TTL | 令牌高效 |
|----------|-----------|-----------|-----------------|-----|-----------------|
| 共享 `.md` 文件 | 部分 | — | — | — | — |
| 环境变量 | 是 | — | — | — | 是 |
| MCP 内存服务器 | 部分 | 变化 | 变化 | — | 变化 |
| **AI 上下文中心** | **6 工具** | **6 种** | **TF-IDF** | **是** | **50 令牌/查询** |
---
## 常见问题
**运行 `enable` 安全吗？** 它会在写入之前备份现有的配置。始终先使用 `--dry-run` 进行审查。
**如果两个工具写入相同的事实怎么办？** `sync` 中的 SHA256 去重捕获重复项。
**它是否支持离线使用？** 是的。所有内容都是本地的。
**为什么不使用数据库？** 零依赖是一个设计约束。JSONL + grep 可以扩展到数千个实体，无需运行时。
**我的数据在哪里？** 默认情况下在 `~/.ai-context/memory/`。使用 `--root` 或 `AI_CONTEXT_ROOT` 覆盖。
MCP 市场