内容
# kortex-memory
适用于大型语言模型（LLMs）和AI编码代理的生产级多租户内存层（Claude Code、Codex、OpenCode）。通过MCP将其插入，您的代理将获得一个共享的、持久的、范围限定且受控访问的内存，该内存跨会话和工具存活。
## 亮点
- **MCP服务器**，支持stdio和HTTP/SSE传输（16种标准工具）。
- **REST API**，全面覆盖内存、对话、附件、导入、导出和租户管理。
- **CLI**（`kortex`），适用于管理员和日常工作流程。
- **Postgres + pgvector**，用于内存、会话和向量搜索。
- **兼容S3的附件**（开发环境使用MinIO，生产环境使用S3/R2）。
- **智能检索** — 大型语言模型计划多跳混合（向量 + BM25 + 最近度）查找；当规划器大型语言模型不可用时，干净地回退到普通混合。
- **短期/中期/长期层级**，具有自动提升、衰减和HDBSCAN合并。
- **敏感性层级 × 基于角色的访问控制**，实现细粒度访问控制。
- **OpenTelemetry跟踪、Prometheus指标、结构化JSON日志**，从第一天开始。
- **幂等性密钥 + ETag/If-Match**，用于API，确保客户端重试安全。
## 文档
| 文档 | 阅读时机 |
|---|---|
| [RUNNING_LOCALLY.md](RUNNING_LOCALLY.md) | 您想在本地机器上尝试Kortex并将其与Claude Code连接。 |
| [DEPLOYMENT.md](DEPLOYMENT.md) | 您正在将Kortex部署到实际的Kubernetes集群。 |
| [RELEASE.md](RELEASE.md) | 您正在发布新的标记版本。 |
| [CHANGELOG.md](CHANGELOG.md) | 您想了解此版本的变更。 |
| [docs/](docs/) | 完整的mkdocs站点（架构、ADRs、运维手册、API参考）。 |
## 项目布局
```
kortex-memory/
├── packages/
│ ├── kortex-core/ # 领域模型、仓库、服务、检索、技能、大型语言模型、存储
│ ├── kortex-api/ # FastAPI REST应用程序（+中间件：上下文、ETag、幂等性、速率限制）
│ ├── kortex-mcp/ # MCP服务器（stdio + SSE），共享一个工具注册表
│ ├── kortex-cli/ # `kortex` Typer CLI（管理员 + 用户）
│ └── kortex-worker/ # Celery工作节点（嵌入、衰减、合并、附件、摘要）+ beat
├── alembic/ # 迁移（3个修订）
├── docker/ # api/mcp/worker Dockerfiles + compose.yaml
├── deploy/
│ ├── helm/kortex/ # 生产环境Helm图表
│ ├── k8s/ # kustomize基础 + 重叠（开发/预发布/生产）
│ └── observability/ # Prometheus规则 + 6个Grafana仪表盘
├── docs/ # mkdocs-material站点
├── tools/ # 自定义CI检查（例如租户检查点）
└── tests/ # 单元测试、集成测试、端到端测试
```
## 30秒快速体验
```bash
# 本地开发 — 完整栈在Docker中
uv sync
make dev && make migrate && make seed
# 尝试使用
export KORTEX_API_URL=http://localhost:8000
export KORTEX_API_KEY=<由make seed打印>
kortex memory create --body "使用Redis，带有5分钟TTL的搜索缓存"
kortex search "caching"
kortex recall "我们决定了什么关于缓存？" --synthesize
# 连接Claude Code — 将以下内容添加到您的MCP配置中：
# { "command": "kortex-mcp", "args": ["stdio"], "env": { "KORTEX_API_KEY": "..." } }
```
完整的操作指南请参见 [RUNNING_LOCALLY.md](RUNNING_LOCALLY.md)。
## 许可证
Apache-2.0。
