内容
# 人物上下文
[](https://github.com/JinyangWang27/people-context/actions/workflows/ci.yml)
[](https://codecov.io/gh/JinyangWang27/people-context)
[](https://scorecard.dev/viewer/?uri=github.com/JinyangWang27/people-context)
[](https://pypi.org/project/people-context/)
[](https://pypi.org/project/people-context/)
[](https://pypi.org/project/people-context/)
[](https://github.com/JinyangWang27/people-context/blob/main/LICENSE)
一个本地优先的MCP服务器和命令行界面，为AI代理提供关于您生活中的人物的持久、用户拥有的上下文。
## 为什么
模型可以识别一个名字，但不知道这个人在用户的生活中的身份。`people-context`在本地SQLite文件中存储身份、别名、关系、角色、持久事实、简洁的交互、通信偏好和后续跟进，然后暴露出解决身份和披露请求所需信息的有限工具。
## 代理插件
### Codex
将仓库作为Codex市场安装，并添加捆绑插件：
```bash
codex plugin marketplace add JinyangWang27/people-context
codex plugin add people-context@people-context-plugins
```
安装后启动新的Codex会话。插件启动本地_stdio_服务器，存储数据在安装的插件副本之外，默认禁用敏感上下文和完整导出工具。参见 [docs/codex-plugin.md](docs/codex-plugin.md) 了解运行时、更新、验证和发布详情。
### Claude Code
将仓库作为Claude Code市场安装，并添加捆绑插件：
```bash
claude plugin marketplace add JinyangWang27/people-context
claude plugin install people-context@people-context-plugins
```
重启Claude Code或运行 `/reload-plugins` 后安装。插件启动本地_stdio_服务器，存储数据在安装的插件副本之外，默认禁用敏感上下文和完整导出工具。参见 [docs/claude-code-plugin.md](docs/claude-code-plugin.md) 了解运行时、更新、验证和发布详情。
### OpenClaw
从ClawHub安装已发布的插件：
```bash
openclaw plugins install clawhub:openclaw-plugin-people-context
openclaw plugins inspect people-context --runtime --json
```
原生OpenClaw插件连接到选择加入的环回HTTP服务器，该服务器必须单独运行。持久写入是可选的，敏感上下文和导出包装器未公开。参见 [docs/openclaw-plugin.md](docs/openclaw-plugin.md) 了解配置、安全、验证和ClawHub发布详情。
## 功能
- 可解释的精确/归一化/全文搜索/模糊身份解析，带有别名和歧义处理；
- 具有敏感性和目的门的有限人员上下文；
- 规范的关系词汇、同义词、逆向对、 对称类型和未分类扩展；
- 具有显式上限/截断的最小披露关系图和最短路径MCP工具；
- 组织和时间感知隶属关系；
- 单独的事实、观察、特征和简洁的交互摘要；
- 基于特征、交互摩擦、提醒和用户创作哲学的通信指导；
- 可审查的电子邮件/mbox/vCard/代理候选导入，不保留原始源内容；
- 可选的固定多语言Model2Vec + `sqlite-vec` 语义检索；
- 每个持久写入的原子审计和重放变更日志/HLC捕获；
- 合并、忘记/删除、未更改的JSON导出和安全的Obsidian保险库导出；
- 默认_stdio_，显式无身份验证的环回仅Streamable HTTP。
## 快速开始
需要Python 3.11+ 和 [`uv`](https://docs.astral.sh/uv/)。
安装发布的发行版，然后启动MCP服务器或人类操作的命令行界面：
```bash
uv tool install people-context
people-context-mcp
people-context --help
```
对于一次性服务器启动，无需持久安装：
```bash
uvx --from people-context people-context-mcp
```
对于本地开发：
```bash
git clone https://github.com/JinyangWang27/people-context.git
cd people-context
uv sync
uv run people-context-mcp
```
环回HTTP是选择加入的：
```bash
uv run people-context-mcp --http --host 127.0.0.1 --port 8765
```
端点是 `http://127.0.0.1:8765/mcp`。它是无身份验证的，必须被视为可被其他本地进程访问。优先使用_stdio_。
## 示例：图感知上下文和保险库
通过MCP记录人员和关系后，使用 `get_relationship_graph` 或 `find_connection` 检查结构，然后创建人类可浏览的保险库：
```bash
uv run people-context export-vault --output ~/PeopleVault
```
目录仅在不存在、为空或已标记为 `.people-context-vault` 时被接受。重新导出在未更改的数据上是字节确定的。敏感/受限事实需要明确的 `--include-sensitive` 标志；导出的文件在服务器披露控制之外。
## 其他MCP客户端
支持本地_stdio_MCP服务器的客户端可以使用：
```json
{
"mcpServers": {
"people-context": {
"command": "uvx",
"args": ["--from", "people-context", "people-context-mcp"]
}
}
}
```
## 安全模型
该项目使用启动用户的文件系统权限执行本地Python。数据库是明文SQLite；依赖文件系统权限和全磁盘加密。普通的MCP发现排除提升的敏感上下文和完整导出。操作员门控工具需要进程环境标志；模型不能通过参数启用它们。保险库导出故意仅限命令行界面。
## 可选语义搜索
基础安装不下载任何内容。显式选择加入：
```bash
uv sync --extra semantic
uv run people-context reindex --semantic
```
只有该重新索引命令可能会下载固定的多语言模型。服务器启动/搜索仅限缓存。
## 数据库位置
服务器和命令行界面使用第一个可用的源：
1. 显式 `--db`/服务器参数；
2. `PEOPLE_CONTEXT_DB`；
3. XDG配置文件中的 `db_path`；
4. `OPENCLAW_WORKSPACE` 或 `~/.openclaw/workspace`；
5. XDG数据备用。
使用 `uv run people-context db-path -v` 检查选定的路径。
## 命令行界面概述
```bash
uv run people-context db-path [-v]
uv run people-context list [--all]
uv run people-context search <query>
uv run people-context show <person>
uv run people-context export [--output FILE]
uv run people-context relationship-types
uv run people-context relationship-types add TYPE --category C [--inverse T | --symmetric]
uv run people-context normalize-relationships [--apply]
uv run people-context export-vault --output DIR [--include-sensitive]
uv run people-context edit PERSON [--name NAME] [--summary TEXT]
uv run people-context add-alias PERSON VALUE [--kind KIND]
uv run people-context set communication_philosophy VALUE
uv run people-context delete PERSON [--yes]
uv run people-context sync-log [--limit N] [--entity ID] [--payloads]
uv run people-context reindex [--semantic]
```
参见 [docs/cli.md](docs/cli.md)。
## 架构
代码库遵循端口和适配器：
```text
适配器 (SQLite, MCP, 文件系统, 导入, 命令行界面)
↓ 实现
端口 (狭窄协议)
↑ 被
应用程序 (用例和策略)
↓ 在
域 (实体和值)
```
依赖关系指向内部。词汇规范化和图上限位于应用程序/域；递归SQL和文件写入位于适配器。 一个组合根同时连接_stdio_和HTTP。
## 文档
| 文档 | 内容 |
|---|---|
| [docs/architecture.md](docs/architecture.md) | 分层、依赖规则、入口点连接 |
| [docs/data-model.md](docs/data-model.md) | 模式、迁移和视角 `display_type` |
| [docs/relationship-graph.md](docs/relationship-graph.md) | 词汇、规范化、视角、遍历、策划 |
| [docs/vault-export.md](docs/vault-export.md) | 布局、标记安全、确定性、敏感性 |
| [docs/mcp-interface.md](docs/mcp-interface.md) | MCP工具和稳定响应契约 |
| [docs/cli.md](docs/cli.md) | 命令行界面命令和数据库解析 |
| [docs/design/sync.md](docs/design/sync.md) | 同步设计和交付的本地基础 |
| [docs/releasing.md](docs/releasing.md) | PyPI受信任发布、Codecov和发布程序 |
| [docs/claude-code-plugin.md](docs/claude-code-plugin.md) | Claude Code安装、运行时、隐私、验证和发布 |
| [docs/codex-plugin.md](docs/codex-plugin.md) | Codex安装、运行时、隐私、验证和发布 |
| [docs/openclaw-plugin.md](docs/openclaw-plugin.md) | OpenClaw安装、运行时、隐私、验证和ClawHub发布 |
| [docs/privacy-and-safety.md](docs/privacy-and-safety.md) | 披露、审计、忘记、威胁模型 |
| [docs/roadmap.md](docs/roadmap.md) | 已交付的里程碑和计划工作 |
| [docs/specs](docs/specs/) | 每个计划里程碑的一个实现规范 |
## 贡献
- 将领域/应用程序与SQLite、MCP和文件系统适配器保持独立。
- 使用狭窄的协议端口和假端口测试应用程序行为。
- 运行 `uv run ruff check .` 和 `uv run pytest -q`。
- 行长为120。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
