内容
# imi
**将团队所有对话和书面内容转化为 AI 代理可查询的知识图谱。**
[](https://github.com/sufficiently-advanced-ai/imi/actions/workflows/tests.yml)
[](https://github.com/sufficiently-advanced-ai/imi/actions/workflows/smoke-test.yml)
[](LICENSE)
imi 是一个自主托管的知识引擎。向其提供文档、通话记录和提交记录 — 它会使用 Claude 进行分类，从中提取实体、决策和行动项到 Neo4j 知识图谱中，并实时为人类（网页界面）和 AI 代理（MCP）提供结果。
## 功能
- **摄入任意内容** — 直接上传、Zapier、GitHub Webhook，或从任意录音机（Otter、Fathom、Grain、Fireflies、Zoom）中丢入通话记录。
- **分类 + 提取** — Claude 对内容进行分类，提取实体和关系，并用领域感知上下文丰富它们。
- **知识图谱** — 每个实体、信号、决策和行动项都进入 Neo4j 图谱（带有内存回退）和 git 支持的 Markdown 语料库。文件是事实来源。
- **受控内存** — 观察结果被提升为具有信任/权威轴和完整审计轨迹的键控信号。代理写入证据；只有人类授予指令级别（[ADR-002](docs/adr/ADR-002-evidence-instruction-authority-gate.md)）。
- **MCP 服务器** — 通过模型上下文协议，Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端都可以搜索、回忆和写回您的知识库。
- **领域无关** — 一个 YAML 模式定义您的实体类型、提取控制和 UI 标签。六个预制领域在 `config/domains/` 中；编写您自己的以适应您的业务。
## 1 · 安装
仅需 Docker — 不需要本地 Python 或 Node。
```bash
docker --version # Docker 24+
docker compose version # Compose v2 — 注意空格：`docker compose`，而不是 `docker-compose`
```
您还需要一个 [Anthropic API 密钥](https://console.anthropic.com)、约 2 GB 的空闲 RAM 和空闲主机端口 `8080`（应用）、`7474` / `7687`（Neo4j）。
```bash
# 1. 克隆
git clone https://github.com/sufficiently-advanced-ai/imi.git
cd imi
# 2. 配置 — 两个必填值，其他值都有默认设置
cp .env.example .env
# ANTHROPIC_API_KEY=sk-ant-...
# NEO4J_PASSWORD=<选择任意密码>
# 3. 构建并启动（首次运行时会拉取镜像并构建前端 — 允许 5–12 分钟）
docker compose up -d --build
```
**验证它已启动。** 应用等待 Neo4j 的健康检查，因此启动不是即时的 — 轮询而不是假设：
```bash
docker compose ps # 两个容器 -> "healthy"
curl -fsS http://localhost:8080/health && echo " OK" # 200 = 启动；连接错误 = 仍在启动
```
网页界面位于 http://localhost:8080。逐步设置并在每一步后验证：[引导手册](docs/getting-started/onboarding.md)。使用 Claude Code 设置？捆绑的 `imi-onboarding` 技能（`.claude/skills/imi-onboarding/`）会引导代理完成整个安装过程。
## 2 · 配置
第一天最重要的决定是您的 **领域** — YAML 模式决定了存在哪些实体类型、提取内容和 UI 调用内容：
| `ACTIVE_DOMAIN` | 构建于 |
|---|---|
| `consulting_firm`（默认） | 账户、项目、人员、团队 |
| `b2b_saas` | 账户、项目、人员 |
| `agency` | 客户、活动、交付成果 |
| `solo_consulting` | 客户、参与、利益相关者 |
| `member_network` | 成员、团体、活动 |
| `personal_crm` | 联系人、公司、活动 |
选择最接近的并在 `.env` 中设置 — 切换到稍后是一个环境变量更改 + 重启。当没有一个合适时，[领域模式指南](docs/customization/domain-schemas.md) 会指导编写自己的模式，而 `domain-config-advisor` 技能可以根据您的业务描述起草一个。
其他一切 — 模型、向量后端、身份验证、git 语料库、遥测 — 都在 [配置参考](docs/getting-started/configuration.md) 中涵盖。人们经常触及的旋钮：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `ANTHROPIC_API_KEY` | **必填** | Claude 认证；如果没有它，什么都提取不了 |
| `NEO4J_PASSWORD` | **必填** | Neo4j 密码（在数据卷的首次初始化时应用） |
| `ACTIVE_DOMAIN` | `consulting_firm` | 哪个领域模式决定了实例 |
| `AUTH_MODE` | `none` | `none`（开放）或 `demo`（cookie 登录）— 在公开之前绑定到环回或代理 |
| `VECTOR_BACKEND` | `sqlite` | 语义内存存储：`sqlite`（持久）或 `pgvector` |
| `GIT_REPO_URL` | — | 支持知识语料库的 GitHub 仓库（[设置指南](docs/getting-started/git-corpus.md)） |
## 3 · 测试
摄入一些内容并观察管道运行：
```bash
curl -X POST http://localhost:8080/api/ingest \
-H "Content-Type: application/json" \
-d '{
"content": "与 Acme Corp 的 Jordan Chen 会议。决定将推出延迟到 Q3。Casey 将在周五前起草迁移计划。",
"title": "Acme 同步",
"source_id": "first-test-1",
"participants": ["Jordan Chen", "Casey Park"]
}'
```
响应是一个带有 `job_id` 的 `202`。检查发生了什么：
```bash
curl -s http://localhost:8080/api/ingest/<job_id>/status # 状态： "completed"
curl -s http://localhost:8080/api/ingest/<job_id>/delta # 人类可读的 "发生了什么" 报告
```
您应该看到实体（Jordan Chen、Casey Park、Acme Corp）、一个 `decision` 信号（“推出延迟到 Q3”）和一个 `action_item`（Casey 的计划）— 在增量报告中，在 http://localhost:8080/explorer 中，或通过 `curl -s http://localhost:8080/api/signals/feed`。
> 始终发送稳定的 `source_id` — 这是幂等键。重新发布相同的键会更新而不是重复。
对于完整的端到端检查（构建、启动、导入扫描、实际摄入）：
```bash
./scripts/smoke_test.sh # 两个阶段；管道阶段需要 ANTHROPIC_API_KEY
./scripts/smoke_test.sh --quick # 仅导入扫描，不需要 API 密钥
```
## 4 · 使用
日常节奏是 **喂养它 → 审查它学到了什么 → 查询它**。完整指南是 [日常使用](docs/getting-started/daily-usage.md)；简版：
**通过 MCP 连接您的 AI 工具。** 复制 `.mcp.json.example` 到 `.mcp.json`（或将等效内容添加到 Claude Desktop / Cursor）：
```json
{ "mcpServers": { "imi": { "type": "sse", "url": "http://localhost:8080/api/mcp/sse" } } }
```
您的代理现在可以调用 `ask_kb`、`search_knowledge_graph`、`memory_recall`、`add_call_transcript` 和其他约 30 个工具 — [MCP & API](docs/architecture/mcp-and-api.md) 中的目录，[代理操作指南](docs/agents/README.md) 中的代理礼仪。
**连接真实输入：**
- **通话记录器** — 将 Zapier zap（或记录器的 Webhook）指向 `POST /api/ingest/zapier`
- **git 知识仓库** — 使用 GitHub 仓库支持语料库以获得异地历史和人工编辑（[设置指南](docs/getting-started/git-corpus.md)）
- **临时想法** — `POST /api/captures` 或 `capture_thought` MCP 工具
**审查和治理。** 概述页面显示需要审查的内容；确认信号是将信号从 *evidence* 提升为 *instruction* — 代理允许视为政策的等级。决策页面跟踪每个决策的生命周期（`active`、`stale`、`superseded`、`conflicting`），以便您始终了解当前决策。
## 文档
完整的套件 — 包含操作员、开发人员和 AI 代理的阅读路径 — 从 [`docs/README.md`](docs/README.md) 开始。亮点：
| 您想… | 阅读 |
|---|---|
| 按验证步骤设置实例 | [引导手册](docs/getting-started/onboarding.md) |
| 查看每个配置旋钮 | [配置参考](docs/getting-started/configuration.md) |
| 使用 GitHub 仓库支持语料库 | [Git 语料库指南](docs/getting-started/git-corpus.md) |
| 日常运行 | [日常使用](docs/getting-started/daily-usage.md) |
| 了解机器的工作原理 | [系统概述](docs/architecture/overview.md) + [架构文档](docs/architecture/) |
| 自定义它 — 配置到代码 | [自定义地图](docs/customization/README.md) |
| 使模式适应您的业务 | [领域模式](docs/customization/domain-schemas.md) |
| 作为 AI 代理操作 | [代理操作指南](docs/agents/README.md) |
| 更改源代码 | [`CLAUDE.md`](CLAUDE.md) / [`AGENTS.md`](AGENTS.md) |
设计记录位于 [`docs/adr/`](docs/adr/)（架构决策）、[`docs/prd/`](docs/prd/)（内存治理和决策状态系统）和 [`docs/world-model-concept.md`](docs/world-model-concept.md)（图谱背后的概念）。
## 故障排除
| 症状 | 原因和解决方法 |
|---|---|
| `imi-neo4j` 保持 `unhealthy`，`imi-app` 永远不会启动 | Neo4j 仅在数据卷的 **首次** 初始化时应用 `NEO4J_PASSWORD`。重置：`docker compose down -v && docker compose up -d --build`（清除数据）。 |
| `curl .../health` 连接被拒绝 | 仍在构建/启动（首次构建需要 5–12 分钟）。在 `Application startup complete` 处监视 `docker compose logs -f app`。 |
| 端口已被占用（`8080` / `7474` / `7687`） | 释放端口或在 `.env` 中更改 `PORT`（应用）；Neo4j 端口位于 `docker-compose.yml`。 |
| 摄入作业返回 `"status": "failed"` | 检查 `docker compose logs app`；缺少或无效的 `ANTHROPIC_API_KEY` 是最常见的原因。 |
| 启动崩溃，提及领域/验证 | 格式错误的领域 YAML — 模式错误在启动时快速失败；错误会命名字段。 |
| 语义搜索/内存回忆返回空值 | 向量索引为空（后端切换，或来自之前的一个记录）。重建一次：`curl -X POST localhost:8080/api/admin/backfill-memory-index`。 |
更多信息请参见 [引导手册的故障排除部分](docs/getting-started/onboarding.md#troubleshooting)。
## 贡献
欢迎提出问题和 PR — [CONTRIBUTING.md](CONTRIBUTING.md) 涵盖了开发环境、测试套件和提取质量评估。设计决策记录在 [`docs/adr/`](docs/adr/) 中。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。依赖项大多是宽松许可的（MIT/BSD/Apache-2.0/ISC），其中包含几个未修改的弱复制库：后端使用 [PyGithub](https://github.com/PyGithub/PyGithub)（LGPL-3.0），前端捆绑了 libvips 原生二进制文件通过 [sharp](https://sharp.pixelplumbing.com/)（LGPL-3.0），一些构建工具是 MPL-2.0。这些都不与 MIT 分发冲突，但如果您重新分发构建镜像，请包含其许可证文本。
