people-context

people-context

English | 简体中文

你的 Agent 已经记住了你的代码库。现在，它也能记住你身边的人。

people-context 是一款本地优先的 MCP 服务和 CLI，可为 AI Agent 提供关于你生活中人们的持久记忆：某人是谁、你们如何相识、你们最后达成了什么共识，以及他们喜欢别人如何与自己交谈。所有数据都存储在你设备上的一个 SQLite 文件中。无需账户，无需云服务，也不会发起网络请求。

为什么

问助手“我该如何和 Priya 谈报告延迟的问题？”，它却一无所知：它不知道你指的是哪位 Priya，不知道她是你在合作组织中的对接人，不知道你们上周商定了新的截止日期，也不知道她更喜欢简短的邮件而不是电话。这些信息存在你的脑海、收件箱和助手无法查看的笔记文件里。

people-context 将这些信息集中在一处，让 Agent 通过范围明确的工具进行查询：

• 这是谁？ 基于姓名、昵称、别名和账号名进行可解释的姓名解析。如果有两位 Priya，系统会返回两位候选人及匹配原因，绝不悄悄猜测。
• 我知道些什么？ 关系、组织和职位、持久事实、简明的互动摘要、特征、提醒，以及每个人的时间线；系统只会按请求所需披露信息。
• 我该如何与他们交流？ 根据记录的特征、过去的摩擦、待跟进事项，以及你自己写下的沟通理念，提供沟通建议。
• 哪些人最近没联系？ 根据已存储的信息，生成关系疏远和即将到来的日期报告。
• 安全导入数据。 邮件、mbox、vCard、日历、LinkedIn、Outlook 和 WhatsApp 导出数据会暂存为可供审核的候选内容。由你批准要记录的内容；系统绝不保留原始来源内容。

它坚持以信任为先：所有写入操作都会记录审计日志，forget 会真正删除数据，敏感记录受仅限操作员的访问闸门保护，提示词无法打开该闸门；普通命令绝不会访问网络。

演示

打包好的虚构数据集是了解身份解析、图遍历和有界上下文的最快方式，而且无需接触真实数据：

uvx --from people-context pctx demo --reset

演示始终会在 {XDG_DATA_HOME or ~/.local/share}/people-context/demo.db 创建专用数据库。它会忽略 --db、PEOPLE_CONTEXT_DB 和配置文件；--reset 只会替换该文件及其 -wal/-shm 配套文件，因此绝不会读取或修改真实数据库。初始化种子数据时，会写入经过审计的虚构人物、标识、所属关系、事实、互动记录和相互连通的关系图，然后打印指定路径的服务命令，以及使用刚创建的 ID 的具体工具调用：

Demo database: /home/you/.local/share/people-context/demo.db
Start MCP server: people-context-mcp --db /home/you/.local/share/people-context/demo.db
resolve_person {"query": "Amina Hassan"}
get_relationship_graph {"person_id": "<amina-id>", "depth": 2}
find_connection {"person_a": "<self-id>", "person_b": "<sofia-id>"}

人物 ID 会在每次初始化时生成，因此打印出的值会与上面的占位符不同。在 MCP 客户端中启动打印出的服务命令，并逐字运行打印出的调用。参见 docs/cli.md。

快速开始

需要 Python 3.11+ 和 uv。选择你的客户端；每种方式都只需一步。

claude plugin marketplace add JinyangWang27/people-context
claude plugin install people-context@people-context-plugins

codex plugin marketplace add JinyangWang27/people-context
codex plugin add people-context@people-context-plugins

{
  "mcpServers": {
    "people-context": {
      "command": "uvx",
      "args": ["--from", "people-context", "people-context"]
    }
  }
}

openclaw plugins install clawhub:openclaw-plugin-people-context

uv tool install people-context
pctx init        # seed your own record, optionally import a vCard, then connect a client
pctx --help

然后在你的 Agent 中试试：

Amina 是谁？

记住，来自 Open City Lab 的 Amina 喜欢简短的邮件，讨厌突如其来的电话。

明天和 Daniel 开会前，我应该了解些什么？

第二条只会调用一次 remember 工具：系统会解析姓名，只有在无人匹配时才创建人物，并在一个经过审计的事务中记录所属关系和偏好。遇到有歧义的姓名时，系统会返回候选项，而不会猜测。

或者，不使用 Agent：运行 pctx remember "Amina Hassan" "prefers short emails" --org "Open City Lab" 和 pctx brief "Amina Hassan"。五个完整示例见 docs/use-cases。

它会记住什么，以及绝不会做什么

对比

带日期并附有供应商文档链接的版本见 docs/privacy-and-safety.md。

安全模型

本项目会以启动用户的文件系统权限执行本地 Python。常规 MCP 发现会排除提升权限的敏感上下文和完整导出。需要操作员授权的工具要求设置进程环境标志；模型无法通过参数启用这些工具。保险库导出特意限定为只能通过 CLI 执行。

默认情况下，数据库是明文 SQLite。在类 Unix 系统上，新建数据库的权限为 0600，因此其他本地账户无法读取。这只是账户之间的隔离边界，并非加密，因此请搭配全磁盘加密，或启用 SQLCipher 静态数据加密（uv sync --extra encrypted；密钥仅读取自 PEOPLE_CONTEXT_DB_KEY）。请参阅 数据库文件权限和 可选的静态数据加密。

深入了解

• Loopback HTTP 适用于无法启动 stdio 的客户端：people-context-mcp --http --host 127.0.0.1 --port 8765。 按设计无需身份验证且仅限本地使用；建议优先使用 stdio。请参阅 docs/cli.md。
• 语义搜索：uv sync --extra semantic && pctx reindex --semantic 会下载固定版本的多语言 Model2Vec 模型一次；服务启动和搜索均仅使用缓存。
• Obsidian：pctx export-vault --output ~/PeopleVault 会生成确定性、可浏览的知识库；只读 Obsidian 插件 可呈现实时简报。请参阅 docs/obsidian-plugin.md。
• 导入：使用 pctx import stage SOURCE PATH，然后执行 review 和 commit，支持通过电子邮件、mbox、vCard、.ics、LinkedIn、Outlook 和 WhatsApp 导出内容。Agent 也可以用同样的方式暂存提取出的候选信息。请参阅 docs/import.md。
• 本地浏览器：pctx browse --open 会提供一个仅限 loopback 访问、由令牌保护的页面，用于浏览联系人，以及审核、编辑和提交暂存的导入批次。请参阅 docs/cli.md。
• 群组：使用 pctx group 记录班级、团队、俱乐部和家庭，然后使用 pctx group shared A B 查询两人如何相识。请参阅 docs/shared-connections-examples.md。
• 报告和维护：pctx stale、pctx upcoming、pctx timeline、pctx doctor、pctx stats。
• 备份和第二台设备：pctx sync push --output DIR 和 pctx sync pull --input PATH。
• Docker：docker run --rm -i -v people-context-data:/data ghcr.io/jinyangwang27/people-context:latest。 这是便捷镜像，并非沙箱。请参阅 docs/docker.md。
• 数据库位置：依次为 --db、PEOPLE_CONTEXT_DB、XDG 配置文件，最后是共享的 ~/.pctx/people.db。使用 pctx db-path -v 查看。

完整的命令参考见 docs/cli.md；MCP 工具清单和响应约定见 docs/mcp-interface.md；跨版本保持稳定的内容见 docs/compatibility.md。

架构

代码库遵循端口与适配器架构：

adapters (SQLite, MCP, filesystem, imports, CLI)
        ↓ implement
ports (narrow Protocols)
        ↑ used by
app (use cases and policy)
        ↓ operates on
domain (entities and values)

依赖关系向内指向。词汇规范化和图谱上限位于 app/domain；递归 SQL 和文件写入位于适配器中。一个组合根负责连接 stdio 和 HTTP。请参阅 docs/architecture.md。

文档

贡献

欢迎提交问题和拉取请求；请参阅 CONTRIBUTING.md，了解架构规则、验证命令和适合作为入门任务的问题列表。欢迎在 Discussions 中提问和展示成果。

如果 people-context 对你有帮助，点个星标可以让更多人发现它。

许可证

MIT。请参阅 LICENSE。