{
  "markdown": "# people-context\n\n<!-- mcp-name: io.github.JinyangWang27/people-context -->\n\n**Your agent already remembers your codebase. Now it can remember your people.**\n\n`people-context` is a local-first [MCP](https://modelcontextprotocol.io) server and CLI that gives AI agents\ndurable memory about the people in your life: who someone is, how you know them, what you last agreed, and how\nthey like to be talked to. One SQLite file on your machine. No account, no cloud, no network calls.\n\n[![CI](https://github.com/JinyangWang27/people-context/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/JinyangWang27/people-context/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/JinyangWang27/people-context/graph/badge.svg)](https://codecov.io/gh/JinyangWang27/people-context)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/JinyangWang27/people-context/badge)](https://scorecard.dev/viewer/?uri=github.com/JinyangWang27/people-context)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13681/badge)](https://www.bestpractices.dev/projects/13681)\n[![PyPI](https://img.shields.io/pypi/v/people-context)](https://pypi.org/project/people-context/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/people-context)](https://pypi.org/project/people-context/)\n[![Python](https://img.shields.io/pypi/pyversions/people-context)](https://pypi.org/project/people-context/)\n[![License](https://img.shields.io/github/license/JinyangWang27/people-context)](https://github.com/JinyangWang27/people-context/blob/main/LICENSE)\n\n![pctx demo: seed a fictional dataset, list people, and print a brief](docs/assets/demo.gif)\n\n## Why\n\nAsk an assistant \"how should I approach Priya about the reporting delay?\" and it has nothing: it does not know\nwhich Priya, that she is your counterpart at a partner org, that you agreed a new deadline last week, or that she\nprefers a short email over a call. That knowledge lives in your head, your inbox, and a notes file the agent\ncannot see.\n\n`people-context` keeps it in one place the agent can query through narrow tools:\n\n- **Who is this?** Explainable name resolution over names, nicknames, aliases, and handles. Two Priyas come back\n  as two candidates with a match reason, never a silent guess.\n- **What do I know?** Relationships, organisations and roles, durable facts, concise interaction summaries,\n  traits, reminders, and a per-person timeline, each disclosed only as far as the request needs.\n- **How do I talk to them?** Communication guidance grounded in recorded traits, past friction, open follow-ups,\n  and your own written philosophy.\n- **Who has gone quiet?** Stale-relationship and upcoming-date reports over what is already stored.\n- **Get data in safely.** Email, mbox, vCard, calendar, LinkedIn, Outlook, and WhatsApp exports are staged as\n  reviewable candidates. You approve what gets recorded; raw source content is never kept.\n\nIt is opinionated about trust: writes are audited, `forget` is a real delete, sensitive records sit behind an\noperator-only gate that a prompt cannot open, and ordinary commands never touch the network.\n\n## Demo\n\nA packaged fictional dataset is the fastest way to see identity resolution, graph traversal, and bounded\ncontext without touching real data:\n\n```bash\nuvx --from people-context pctx demo --reset\n```\n\nThe demo always writes its own dedicated database at\n`{XDG_DATA_HOME or ~/.local/share}/people-context/demo.db`. It ignores `--db`, `PEOPLE_CONTEXT_DB`, the config\nfile, and workspace discovery, and `--reset` replaces only that file plus its `-wal`/`-shm` companions, so a\nreal database is never read or modified. Seeding writes audited fictional people, handles, affiliations, facts,\ninteractions, and a connected relationship graph, then prints the path-targeted server command and concrete\ntool calls that use the ids it just created:\n\n```text\nDemo database: /home/you/.local/share/people-context/demo.db\nStart MCP server: people-context-mcp --db /home/you/.local/share/people-context/demo.db\nresolve_person {\"query\": \"Amina Hassan\"}\nget_relationship_graph {\"person_id\": \"<amina-id>\", \"depth\": 2}\nfind_connection {\"person_a\": \"<self-id>\", \"person_b\": \"<sofia-id>\"}\n```\n\nPerson ids are generated per seed, so the printed values differ from the placeholders above. Start the printed\nserver command in an MCP client and run the printed calls verbatim. See\n[docs/cli.md](docs/cli.md#packaged-demo).\n\n## Quick start\n\nRequires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/). Pick your client; each is one step.\n\n<details open>\n<summary><b>Claude Code</b></summary>\n\n```bash\nclaude plugin marketplace add JinyangWang27/people-context\nclaude plugin install people-context@people-context-plugins\n```\n\nRestart Claude Code or run `/reload-plugins`. You get the server plus `/people-context:who`,\n`/people-context:remember`, and `/people-context:reminders`. Details: [docs/claude-code-plugin.md](docs/claude-code-plugin.md).\n</details>\n\n<details>\n<summary><b>Claude Desktop</b></summary>\n\nDownload `people-context.mcpb` from the\n[latest release](https://github.com/JinyangWang27/people-context/releases/latest) and open it. Claude Desktop\ninstalls the pinned release with its own `uv` runtime. Details: [docs/desktop-and-editors.md](docs/desktop-and-editors.md).\n</details>\n\n<details>\n<summary><b>Codex</b></summary>\n\n```bash\ncodex plugin marketplace add JinyangWang27/people-context\ncodex plugin add people-context@people-context-plugins\n```\n\nStart a new Codex session. Details: [docs/codex-plugin.md](docs/codex-plugin.md).\n</details>\n\n<details>\n<summary><b>Cursor, Windsurf, VS Code, or any MCP client</b></summary>\n\nAdd the stdio server to your client's MCP config (`.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`,\n`.vscode/mcp.json`, ...):\n\n```json\n{\n  \"mcpServers\": {\n    \"people-context\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"people-context\", \"people-context\"]\n    }\n  }\n}\n```\n\nOr let the CLI write it: `uvx --from people-context pctx setup cursor` (also `windsurf`, `vscode`,\n`claude-desktop`; add `--dry-run` to preview). VS Code uses a `servers` key with `\"type\": \"stdio\"`. Per-editor\nsnippets: [docs/desktop-and-editors.md](docs/desktop-and-editors.md).\n</details>\n\n<details>\n<summary><b>OpenClaw</b></summary>\n\n```bash\nopenclaw plugins install clawhub:openclaw-plugin-people-context\n```\n\nThe native plugin talks to the opt-in loopback HTTP server. Details: [docs/openclaw-plugin.md](docs/openclaw-plugin.md).\n</details>\n\n<details>\n<summary><b>CLI only</b></summary>\n\n```bash\nuv tool install people-context\npctx init        # seed your own record, optionally import a vCard, then connect a client\npctx --help\n```\n\n`people-context` and `people-context-mcp` are the server commands; `pctx` is the human-operated CLI.\n</details>\n\nThen try, in your agent:\n\n> Who is Amina?\n>\n> Remember that Amina from Open City Lab prefers short emails and hates surprise calls.\n>\n> What should I know before my meeting with Daniel tomorrow?\n\nThe second one is a single `remember` tool call: the name is resolved, the person is created only if nobody\nmatches, and the affiliation and preference are recorded in one audited transaction. Ambiguous names come back\nas candidates, never a guess.\n\nOr, without an agent: `pctx remember \"Amina Hassan\" \"prefers short emails\" --org \"Open City Lab\"` and\n`pctx brief \"Amina Hassan\"`. Five worked scenarios live in [docs/use-cases](docs/use-cases/README.md).\n\n## What it remembers, and what it never does\n\n| It remembers | It never does |\n|---|---|\n| Names, nicknames, aliases, and handles | Upload anything, anywhere |\n| Relationships with a canonical, extensible vocabulary | Store raw imported emails, chats, or files |\n| Organisations, roles, and time-bounded affiliations | Let a model enable sensitive disclosure or full export |\n| Durable facts, observations, and traits with evidence | Commit imported or agent-extracted data without your review |\n| Concise interaction summaries and a per-person timeline | Log private values or keep a soft-deleted copy after `forget` |\n| Reminders, follow-ups, and your communication philosophy | Make a network request outside `pctx reindex --semantic` |\n\n## How it compares\n\n| | `people-context` | Assistant memory (ChatGPT, Claude) | Memory platforms (Mem0 and similar) |\n|---|---|---|---|\n| Where data lives | One SQLite file you own | Vendor account | Vendor platform or your own deployment |\n| Works offline | Yes | No | Self-hosted only |\n| Knows *people* as first-class records | Identity, relationships, roles, graph, guidance | Free-text notes | Free-text or vector memories |\n| Explains a match | Ranked candidates with a reason; ambiguity is surfaced | No | Similarity score |\n| Import review gate | Stage, review, commit | n/a | Automatic extraction |\n| Deletion | Hard delete plus audit redaction in one transaction | Request to vendor | API delete |\n| Backup and move | `pctx sync push` / `pull` bundle | n/a | Deployment-specific |\n\nThe dated, sourced version with vendor documentation links is in\n[docs/privacy-and-safety.md](docs/privacy-and-safety.md#local-first-versus-cloud-hosted-memory-as-of-2026-08-05).\n\n## Security model\n\nThis project executes local Python with the launching user's filesystem permissions. Ordinary MCP discovery\nexcludes elevated sensitive context and full export. Operator-gated tools require process environment flags;\nmodels cannot enable them through arguments. Vault export is intentionally CLI-only.\n\nThe database is plaintext SQLite by default. On Unix-like systems a new one is created `0600`, so other local\naccounts cannot read it. That is a boundary between accounts, not encryption, so pair it with full-disk\nencryption or opt into SQLCipher at-rest encryption (`uv sync --extra encrypted`, key read only from\n`PEOPLE_CONTEXT_DB_KEY`). See\n[database file permissions](docs/privacy-and-safety.md#database-file-permissions) and\n[optional at-rest encryption](docs/privacy-and-safety.md#optional-at-rest-encryption).\n\n## Going further\n\n- **Loopback HTTP** for clients that cannot spawn stdio: `people-context-mcp --http --host 127.0.0.1 --port 8765`.\n  Unauthenticated and local-only by design; prefer stdio. See [docs/cli.md](docs/cli.md).\n- **Semantic search**: `uv sync --extra semantic && pctx reindex --semantic` downloads a pinned multilingual\n  Model2Vec model once; server startup and search stay cache-only.\n- **Obsidian**: `pctx export-vault --output ~/PeopleVault` writes a deterministic, browsable vault, and a\n  read-only [Obsidian plugin](obsidian-plugin/) renders live briefs. See [docs/obsidian-plugin.md](docs/obsidian-plugin.md).\n- **Import**: `pctx import stage SOURCE PATH` then `review` and `commit`, over email, mbox, vCard, `.ics`,\n  LinkedIn, Outlook, and WhatsApp exports. Agents can stage extracted candidates the same way. See\n  [docs/import.md](docs/import.md).\n- **Reports and maintenance**: `pctx stale`, `pctx upcoming`, `pctx timeline`, `pctx doctor`, `pctx stats`.\n- **Backup and second device**: `pctx sync push --output DIR` and `pctx sync pull --input PATH`.\n- **Docker**: `docker run --rm -i -v people-context-data:/data ghcr.io/jinyangwang27/people-context:latest`.\n  A convenience image, not a sandbox. See [docs/docker.md](docs/docker.md).\n- **Database location**: `--db`, then `PEOPLE_CONTEXT_DB`, then the XDG config file, then an OpenClaw workspace,\n  then the XDG data directory. Inspect with `pctx db-path -v`.\n\nThe full command reference is in [docs/cli.md](docs/cli.md); the MCP tool inventory and response contracts are\nin [docs/mcp-interface.md](docs/mcp-interface.md); what stays stable across releases is in\n[docs/compatibility.md](docs/compatibility.md).\n\n## Architecture\n\nThe codebase follows ports and adapters:\n\n```text\nadapters (SQLite, MCP, filesystem, imports, CLI)\n        ↓ implement\nports (narrow Protocols)\n        ↑ used by\napp (use cases and policy)\n        ↓ operates on\ndomain (entities and values)\n```\n\nDependencies point inward. Vocabulary normalization and graph caps live in app/domain; recursive SQL and file\nwriting live in adapters. One composition root wires both stdio and HTTP. See\n[docs/architecture.md](docs/architecture.md).\n\n## Documentation\n\n| Document | Contents |\n|---|---|\n| [docs/architecture.md](docs/architecture.md) | Layering, dependency rule, entrypoint wiring |\n| [docs/data-model.md](docs/data-model.md) | Schema, migrations, and perspective `display_type` |\n| [docs/relationship-graph.md](docs/relationship-graph.md) | Vocabulary, normalization, perspective, traversal, curation |\n| [docs/vault-export.md](docs/vault-export.md) | Layout, marker safety, determinism, sensitivity |\n| [docs/mcp-interface.md](docs/mcp-interface.md) | MCP tools and stable response contracts |\n| [docs/compatibility.md](docs/compatibility.md) | What stays stable across releases for MCP, DB, CLI, and JSON |\n| [docs/cli.md](docs/cli.md) | CLI commands and DB resolution |\n| [docs/import.md](docs/import.md) | Import sources, staging, review, and commit |\n| [docs/design/sync.md](docs/design/sync.md) | Sync design and delivered local foundations |\n| [docs/releasing.md](docs/releasing.md) | PyPI trusted publishing, Codecov, and release procedure |\n| [docs/mcp-registry.md](docs/mcp-registry.md) | MCP Registry namespace, `server.json`, and community-directory submission matrix |\n| [docs/distribution-checklist.md](docs/distribution-checklist.md) | Account-owner walkthrough: Registry publish, directories, awesome lists, Desktop directory, Obsidian |\n| [docs/desktop-and-editors.md](docs/desktop-and-editors.md) | Native-UV MCPB Desktop bundle and Cursor/Windsurf/VS Code snippets |\n| [docs/docker.md](docs/docker.md) | Optional non-root stdio Docker image, data volume, and GHCR publishing |\n| [docs/claude-code-plugin.md](docs/claude-code-plugin.md) | Claude Code install, runtime, privacy, validation, and publishing |\n| [docs/codex-plugin.md](docs/codex-plugin.md) | Codex install, runtime, privacy, validation, and publishing |\n| [docs/openclaw-plugin.md](docs/openclaw-plugin.md) | OpenClaw install, runtime, privacy, validation, and ClawHub publishing |\n| [docs/obsidian-plugin.md](docs/obsidian-plugin.md) | Obsidian read-only panes, subprocess safety, encryption, and mirrored releases |\n| [docs/privacy-and-safety.md](docs/privacy-and-safety.md) | Disclosure, audit, forget, threat model |\n| [docs/use-cases](docs/use-cases/README.md) | Narrative recipes for onboarding, meeting prep, follow-up, migration, and auditing |\n| [docs/evals.md](docs/evals.md) | Evaluation harness, fixed tasks, scoring rules, and dated recorded results |\n| [docs/roadmap.md](docs/roadmap.md) | Delivered milestones and planned work |\n| [docs/specs](docs/specs/) | One implementation spec per planned milestone |\n\n## Contributing\n\nIssues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) for the architecture rules,\nvalidation commands, and a list of good first issues. Questions and show-and-tell go to\n[Discussions](https://github.com/JinyangWang27/people-context/discussions).\n\nIf `people-context` is useful to you, a star helps other people find it.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 15161,
  "sha": "281cbed7da8e65b7dfa39c6cf80138eb96791ae66bc3c618ed1d1147d956d0e4",
  "repo_slug": "jinyangwang27/people-context",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jinyangwang27_people_context_2c26d2b2/readme"
}