@reconcrap/people-network-memory 0.1.0

package/README.md

@@ -0,0 +1,476 @@
+# People Network Memory MCP
+
+Local-first V1 scaffold for a personal social-memory MCP. The implementation keeps the product logic independent from Graphiti/MCP/OpenClaw so the core can be tested without external services.
+
+## Quick Commands
+
+```powershell
+python -m pip install -e .
+python -m unittest discover -s tests -v
+people-memory start --test-mode --once
+people-memory doctor --test-mode
+people-memory load-fixtures --summary
+people-memory eval-fixtures
+people-memory eval-fixtures --failures-only --output .people-network-memory/eval-report.json
+people-memory spike-graphiti
+people-memory check-embedding
+people-memory tool-schemas
+people-memory smoke-graphiti --isolated
+people-memory graphiti-gate --isolated --output .people-network-memory/graphiti-gate.json
+people-memory index-graphiti --resume --limit 10 --output .people-network-memory/index-graphiti.json
+people-memory graphiti-ladder --steps 1,3,10 --cumulative --output-dir .people-network-memory/test-artifacts/graphiti-ladder
+people-memory smoke-openclaw
+people-memory eval-harness-integration
+people-memory release-check
+people-memory eval-graphiti --isolated --max-interactions 3 --max-queries 3
+people-memory install-openclaw --dry-run
+people-memory list-reviews
+people-memory backup --output .people-network-memory/backup.json
+people-memory backup-archive --output .people-network-memory/backup.zip
+people-memory restore --input .people-network-memory/backup.json
+```
+
+The base test suite uses `unittest` and does not require Graphiti, Docker, or a graph
+database:
+
+```powershell
+python -m unittest discover -s tests -v
+python -m people_network_memory.cli release-check
+powershell -ExecutionPolicy Bypass -File .\scripts\run_tests_with_artifacts.ps1
+```
+
+The artifact runner writes command output, JSON reports, and a manifest with
+exit codes to `.people-network-memory/test-artifacts/latest/` by default. That
+directory is ignored by git so local verification reports do not leak into the
+package.
+
+## Local Install
+
+### npm Install
+
+The recommended end-user distribution path is the npm wrapper. It keeps the
+product code in Python, but gives OpenClaw users a familiar install/update
+surface:
+
+```powershell
+npm install -g @reconcrap/people-network-memory
+people-memory doctor --test-mode
+people-memory install-openclaw --backend local_json
+people-memory doctor --agent openclaw
+```
+
+The npm `people-memory` command lazily creates a private Python 3.11+ venv and
+installs this package into it. The default venv locations are:
+
+- Windows: `%LOCALAPPDATA%\people-network-memory\npm-venv`
+- macOS: `~/Library/Application Support/people-network-memory/npm-venv`
+- Linux: `${XDG_DATA_HOME:-~/.local/share}/people-network-memory/npm-venv`
+
+Set `PEOPLE_MEMORY_NPM_VENV` to override that location, or
+`PEOPLE_MEMORY_PYTHON` to choose a specific Python command. For Graphiti extras,
+either run with `--backend graphiti` or set
+`PEOPLE_MEMORY_NPM_EXTRAS=graphiti`.
+
+When `install-openclaw` is run through the npm command, the installer writes
+OpenClaw to launch the absolute Node executable plus the npm wrapper script.
+That keeps the MCP server independent of shell PATH differences between visible
+terminals and hidden OpenClaw gateway sessions on Windows and macOS.
+
+Update flow:
+
+```powershell
+npm update -g @reconcrap/people-network-memory
+people-memory install-openclaw --backend local_json
+```
+
+### Source Checkout Install
+
+For a clean Windows checkout, use the bootstrap script. It creates `.venv`,
+installs the package, runs the test suite, runs `doctor`, and starts the MCP
+server once in test mode:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1
+```
+
+Install optional Graphiti/Kuzu dependencies as part of the same flow:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1 -Graphiti
+```
+
+To also wire OpenClaw to a managed bootstrap command:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1 -OpenClaw
+```
+
+The managed OpenClaw entry starts `scripts/people_memory_bootstrap.py`. On each
+server start, that bootstrapper checks for a local `.venv`, creates it if
+missing, installs or updates dependencies when `pyproject.toml` changes, then
+launches the MCP server from the venv. This lets an AI harness repair missing
+Python package dependencies without the user manually running pip.
+
+For a trusted git checkout, add `-AutoUpdate` to let the bootstrapper run
+`git pull --ff-only` before dependency checks:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1 -OpenClaw -AutoUpdate
+```
+
+This still requires a system Python 3.11+ command to exist. On Windows the
+managed entry uses `py -3.11`; on macOS/Linux it uses `python3`.
+
+For Graphiti-backed OpenClaw, first configure the embedding and LLM environment
+variables in OpenClaw or the launching shell, then run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1 -Graphiti -OpenClaw -Backend graphiti
+```
+
+The bootstrap script does not write API keys or model credentials.
+
+For the current Windows development setup, the live Graphiti artifact run can
+reuse Volcengine/Doubao embeddings and the LLM values from the Liepin screening
+config:
+
+```powershell
+$env:VOLCENGINE_API_KEY="<secret>"
+powershell -ExecutionPolicy Bypass -File .\scripts\run_graphiti_live_from_liepin.ps1
+```
+
+That wrapper maps the embedding endpoint/model to Volcengine, reads
+`baseUrl`/`model`/credential from `~/.liepin-recommend-mcp/screening-config.json`
+for the LLM provider, disables Graphiti telemetry, and stores verification
+artifacts under `.people-network-memory/test-artifacts/graphiti-live/`.
+
+`spike-graphiti` is the prerequisite gate. `graphiti-gate` is the promotion
+gate: it keeps `local_json` as the default, runs live embedding plus a full
+Graphiti/Kuzu fixture eval when providers are configured, and reports whether
+Graphiti/Kuzu is ready to become the recommended recall backend.
+
+## Backends
+
+- `local_json` is the default non-test backend and persists to
+  `~/.people-network-memory/people-memory.json`.
+- `inmemory` is used for tests and quick smoke checks.
+- `graphiti` is gated behind `people-memory graphiti-gate`; do not treat it as
+  the recommended recall backend until that command passes with live providers.
+- For local Graphiti, prefer embedded Kuzu first. It avoids Docker and server setup.
+
+Python 3.11 venv setup for Graphiti + Kuzu:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install -e ".[graphiti]"
+.\.venv\Scripts\python.exe -m people_network_memory.cli spike-graphiti
+.\.venv\Scripts\python.exe -m people_network_memory.cli smoke-graphiti --isolated
+.\.venv\Scripts\python.exe -m people_network_memory.cli eval-graphiti --isolated --max-interactions 3 --max-queries 3 --output .people-network-memory/graphiti-eval.json
+.\.venv\Scripts\python.exe -m people_network_memory.cli graphiti-gate --isolated --output .people-network-memory/graphiti-gate.json
+```
+
+Eval reports include Recall@3, Recall@5, per-category breakdowns, evidence
+coverage, no-result counts, sensitive-leak counts, and optional case-level
+diagnostics. When `--max-interactions` is used, evals default to queries whose
+source fixture interactions were ingested. Add `--all-queries` only when you
+intentionally want to test missing/unanswerable targets.
+
+Case-level diagnostics include the query, expected people/terms, matched and
+missed expected values, and the actual top retrieval results with evidence
+source text/date. The artifact runner saves these full case diagnostics by
+default in `eval-fixtures.json`; Graphiti live artifacts save them in
+`graphiti-gate.json` and `graphiti-eval.json`.
+
+`eval-graphiti` without `--max-*` runs the full fixture set. The small bounded
+form above is only a quick smoke check. `graphiti-gate` uses the full fixture
+set by default and requires Recall@3 >= 70%, Recall@5 >= 85%, complete returned
+evidence, zero sensitive leaks, at least 40 checked queries, and at least 60
+ingested interactions unless you intentionally bound the run.
+
+Graphiti indexing should be treated as resumable background work. Local JSON is
+the canonical capture store; `index-graphiti` reads saved local interactions and
+adds compact text episodes into Graphiti/Kuzu one by one, saving progress after
+each successful episode:
+
+```powershell
+people-memory index-graphiti --resume --limit 10 --output .people-network-memory/index-graphiti.json
+people-memory index-graphiti --resume --limit 10
+```
+
+Use the ingestion ladder to find the point where the live Graphiti/LLM path
+slows down or fails. Each step writes a separate JSON artifact:
+
+```powershell
+people-memory graphiti-ladder --steps 1,3,10,20,40,90 --output-dir .people-network-memory/test-artifacts/graphiti-ladder
+```
+
+Add `--cumulative` when testing larger rungs. It reuses one artifact-local
+Graphiti/Kuzu store plus one state file, so a `20,40,90` run indexes only the
+additional interactions at each step and leaves the test database under the
+artifact directory:
+
+```powershell
+people-memory graphiti-ladder --steps 20,40,90 --cumulative --output-dir .people-network-memory/test-artifacts/graphiti-ladder-cumulative
+```
+
+If that command is interrupted, rerun it with `--resume-cumulative` against the
+same output directory to keep the existing state file:
+
+```powershell
+people-memory graphiti-ladder --steps 20,40,90 --cumulative --resume-cumulative --output-dir .people-network-memory/test-artifacts/graphiti-ladder-cumulative
+```
+
+For slow live providers, raise the per-episode timeout without changing code:
+
+```powershell
+$env:PEOPLE_MEMORY_GRAPHITI_ADD_TIMEOUT_SECONDS="600"
+$env:PEOPLE_MEMORY_GRAPHITI_RETRY_ATTEMPTS="4"
+people-memory graphiti-ladder --steps 20,40,90 --cumulative --resume-cumulative --output-dir .people-network-memory/test-artifacts/graphiti-ladder-cumulative
+```
+
+Bounded ladder runs are diagnostics only; they cannot promote Graphiti/Kuzu to
+the recommended backend.
+
+After an existing Graphiti/Kuzu fixture graph has been indexed, evaluate search
+quality without re-ingesting episodes:
+
+```powershell
+people-memory eval-graphiti-search --data-path .people-network-memory/test-artifacts/graphiti-ladder-cumulative/cumulative-store/projection --graphiti-kuzu-path .people-network-memory/test-artifacts/graphiti-ladder-cumulative/cumulative-store/graphiti.kuzu --indexed-interactions 90 --output .people-network-memory/test-artifacts/graphiti-search/eval.json
+```
+
+If the graph was populated by the fixture ladder before the projection cache was
+hydrated, rebuild that local cache without calling Graphiti again:
+
+```powershell
+people-memory hydrate-graphiti-cache --data-path .people-network-memory/test-artifacts/graphiti-ladder-cumulative/cumulative-store/projection --fixture-seed 42 --limit 90 --output .people-network-memory/test-artifacts/graphiti-search/cache-hydration.json
+```
+
+Build the optional local semantic sidecar over the hydrated projection cache:
+
+```powershell
+people-memory build-semantic-cache --data-path .people-network-memory/test-artifacts/graphiti-ladder-cumulative/cumulative-store/projection --limit 90 --reset --output .people-network-memory/test-artifacts/graphiti-search/semantic-cache.json
+```
+
+With that sidecar present, Graphiti retrieval merges three sources: Graphiti
+graph search, local semantic interaction search, and local token/event search.
+The strict eval report checks intent-aware matches, not just loose token
+overlap: `who mentioned X` must return the speaker, promise queries must return
+follow-up items, and profile queries must combine the requested terms in one
+returned result. For intentionally broad fixture queries, the report also keeps
+`expected_person_rank` as a diagnostic because several mock people may satisfy
+the same place/topic or company/topic query.
+
+## Optional LLM Retrieval Judge
+
+The default retrieval path is deterministic and fully testable. For a final
+quality pass, enable the optional OpenAI-compatible LLM judge:
+
+```powershell
+$env:PEOPLE_MEMORY_RETRIEVAL_JUDGE="llm"
+$env:PEOPLE_MEMORY_RETRIEVAL_JUDGE_TIMEOUT_SECONDS="30"
+$env:PEOPLE_MEMORY_LLM_BASE_URL="<base-url>"
+$env:PEOPLE_MEMORY_LLM_MODEL="<model>"
+$env:PEOPLE_MEMORY_LLM_API_KEY="<secret>"
+```
+
+When enabled, `retrieve_network_context` fetches a broader candidate set, asks
+the judge to rank only candidates that directly answer the query, and falls back
+to deterministic ranking if the judge fails or returns invalid JSON.
+
+The intended harness split is hybrid:
+
+- This tool owns social-memory retrieval quality: query expansion, graph/semantic
+  search, deterministic social-intent checks, optional LLM reranking, evidence,
+  sensitivity policy, and stable person IDs.
+- The AI harness owns user-aware synthesis: applying its memory of the user's
+  goals, style, preferences, and current constraints to the retrieved social
+  evidence.
+- The OpenClaw skill instructs the harness to retrieve from this MCP first,
+  treat returned people/network facts as source-backed evidence, then combine
+  them with the harness's own user memory for final recommendations, briefs,
+  drafts, or plans.
+
+Run the deterministic harness integration eval to check that contract without
+needing a live AI harness:
+
+```powershell
+people-memory eval-harness-integration --output .people-network-memory/harness-integration-eval.json
+```
+
+The eval seeds a small social graph and verifies planning, intro drafting,
+conflict resolution, missing-person evidence, and follow-up cases. Each case
+records the prompt, simulated harness memory, MCP tool calls, actual retrieval
+results, hydrated person cards when needed, and pass/fail checks for source
+boundaries.
+
+## LLM Ingestion Extractor
+
+The capture path defaults to the OpenAI-compatible LLM extractor when usable,
+then falls back to deterministic normalization. This improves messier Chinese,
+alias, and bilingual social notes without making a fresh install depend on LLM
+credentials. To provide an LLM, set:
+
+```powershell
+$env:PEOPLE_MEMORY_INGESTION_EXTRACTOR="llm"
+$env:PEOPLE_MEMORY_INGESTION_EXTRACTOR_TIMEOUT_SECONDS="30"
+$env:PEOPLE_MEMORY_LLM_BASE_URL="<base-url>"
+$env:PEOPLE_MEMORY_LLM_MODEL="<model>"
+$env:PEOPLE_MEMORY_LLM_API_KEY="<secret>"
+```
+
+The extractor proposes participants, aliases, topics, claims, relationships,
+and follow-ups from `source_text`. The application layer still preserves the
+original note as evidence, strips model-invented `person_id` values, applies the
+deterministic normalizer, and sends identity ambiguity to review instead of
+silently merging cards. If the extractor fails or returns invalid JSON, capture
+falls back to the deterministic rules.
+
+To force deterministic-only capture:
+
+```powershell
+$env:PEOPLE_MEMORY_INGESTION_EXTRACTOR="off"
+```
+
+OpenClaw installs default to `PEOPLE_MEMORY_INGESTION_EXTRACTOR=llm`. Use
+`people-memory install-openclaw --ingestion-extractor off` only when you want to
+disable the LLM extraction pass for that harness.
+
+## Embeddings
+
+Local-first default recommendation:
+
+```powershell
+$env:PEOPLE_MEMORY_EMBEDDING_PROVIDER="ollama"
+$env:PEOPLE_MEMORY_EMBEDDING_BASE_URL="http://localhost:11434/v1"
+$env:PEOPLE_MEMORY_EMBEDDING_MODEL="nomic-embed-text"
+people-memory check-embedding
+```
+
+OpenAI-compatible cloud endpoints use the same command with:
+
+```powershell
+$env:PEOPLE_MEMORY_EMBEDDING_PROVIDER="openai_compatible"
+$env:PEOPLE_MEMORY_EMBEDDING_BASE_URL="https://ark.cn-beijing.volces.com/api/coding/v3"
+$env:PEOPLE_MEMORY_EMBEDDING_MODEL="doubao-embedding-vision-251215"
+$env:PEOPLE_MEMORY_EMBEDDING_API_KEY="<secret>"
+people-memory check-embedding
+```
+
+Do not commit API keys or write them into config files.
+
+## Sensitivity Policy
+
+Sensitivity labels such as `sensitive` and `do_not_surface_unprompted` are kept
+as metadata, but V1 defaults to `personal` surfacing because this is a private
+single-user memory tool.
+
+```powershell
+$env:PEOPLE_MEMORY_SENSITIVITY_POLICY="personal"    # private recall includes sensitive context
+$env:PEOPLE_MEMORY_SENSITIVITY_POLICY="strict"      # hide sensitive context unless explicitly requested
+$env:PEOPLE_MEMORY_SENSITIVITY_POLICY="task_aware"  # include for private recall, hide for shareable output
+```
+
+The MCP retrieval tool also accepts `sensitivity_policy`, `output_context`, and
+the explicit `include_sensitive` override per request.
+
+Graphiti also needs an LLM provider for episode extraction. Embeddings alone are
+enough for vector smoke checks, but not enough for live Graphiti ingestion.
+Some OpenAI-compatible gateways do not support `response_format`; leave
+`PEOPLE_MEMORY_LLM_RESPONSE_FORMAT` unset or set it to `none` for those
+providers. Use `json_object` or `json_schema` only when the provider explicitly
+supports that mode.
+
+```powershell
+$env:PEOPLE_MEMORY_BACKEND="graphiti"
+$env:PEOPLE_MEMORY_GRAPH_BACKEND="kuzu"
+$env:PEOPLE_MEMORY_LLM_PROVIDER="openai_compatible"
+$env:PEOPLE_MEMORY_LLM_BASE_URL="<base-url>"
+$env:PEOPLE_MEMORY_LLM_MODEL="<model>"
+$env:PEOPLE_MEMORY_LLM_API_KEY="<secret>"
+$env:PEOPLE_MEMORY_LLM_RESPONSE_FORMAT="none"
+.\.venv\Scripts\python.exe -m people_network_memory.cli smoke-graphiti --isolated
+```
+
+`reset` is intentionally guarded:
+
+```powershell
+people-memory reset --confirm DELETE
+```
+
+It deletes only the configured local JSON data file for `local_json`.
+
+## Backup
+
+Use JSON backup for portable person-card projection data:
+
+```powershell
+people-memory backup --output .people-network-memory/backup.json
+people-memory restore --input .people-network-memory/backup.json
+```
+
+Use archive backup when the backend has local storage beyond the projection
+cache. For `graphiti` + Kuzu, the archive includes `projection.json` and the
+configured Kuzu database directory:
+
+```powershell
+people-memory backup-archive --backend graphiti --output .people-network-memory/graphiti-backup.zip
+people-memory restore-archive --backend graphiti --input .people-network-memory/graphiti-backup.zip --confirm OVERWRITE
+```
+
+`restore-archive` requires explicit confirmation and rejects unsafe archive
+member paths.
+
+## Low-Friction Capture
+
+The MCP tool accepts raw `source_text` first. If the harness can confidently
+extract structure, it should include it. If not, it can still send the original
+note and the server will conservatively normalize obvious people, places,
+topics, mentions, work/school facts, contacts, interests, and follow-ups.
+
+## Review Queue
+
+Ambiguous identity matches are captured without blocking the original note. Use
+the review commands to clean them up later:
+
+```powershell
+people-memory list-reviews
+people-memory resolve-review --review-id review_0001 --source-person-id person_0003 --target-person-id alice
+people-memory dismiss-review --review-id review_0002 --note "not enough information"
+```
+
+Resolving an identity review merges the source person into the target person,
+preserves aliases, interactions, facts, claims, follow-ups, relationships, and
+evidence, then marks the review item as resolved.
+
+## OpenClaw
+
+Install or preview the OpenClaw adapter:
+
+```powershell
+people-memory install-openclaw --dry-run
+people-memory install-openclaw
+people-memory install-openclaw --managed-bootstrap
+people-memory doctor --agent openclaw
+people-memory smoke-openclaw
+people-memory eval-harness-integration
+```
+
+The installer updates only the `people-network-memory` MCP server entry in the
+active OpenClaw config. Current OpenClaw builds use `~/.openclaw/openclaw.json`
+under `mcp.servers`; when that file exists the installer updates it, and also
+maintains the legacy/generic `~/.openclaw/mcp.json` shape for older MCP
+harnesses. It preserves unrelated MCP servers and writes the mirrored skill to
+`~/.openclaw/skills/ppl/SKILL.md`. The MCP server namespace remains
+`people-network-memory` for tool compatibility, but the user-facing OpenClaw
+slash trigger is `/ppl`; `/people_network_memory` and `/people-network-memory`
+remain accepted aliases for existing prompts.
+By default it uses the active Python executable with
+`-m people_network_memory.cli start`, so it does not require the `people-memory`
+console script to be on PATH. For end-user harness installs, prefer
+`--managed-bootstrap`: that stores a tiny stdlib launcher in the MCP command so
+the harness can recreate the venv and refresh Python dependencies automatically.
+
+`smoke-openclaw` installs into a temporary OpenClaw home by default, checks the
+adapter config and skill text, verifies prompt-routing examples, and exercises
+the three public MCP workflows with the test backend.

package/docs/mcp_tools.md

@@ -0,0 +1,138 @@
+# MCP Tool Contract
+
+V1 exposes exactly three public tools. The machine-readable source of truth is:
+
+```powershell
+people-memory tool-schemas
+```
+
+Adapters should treat the schema as stable within contract version `v1`.
+
+## record_interaction
+
+Use for a meeting, coffee, dinner, call, message, intro, event, or loose memory
+note. The required field is `source_text`; all structured fields are optional so
+the harness can preserve the user's original wording and add structure only when
+it can do so confidently.
+
+The server performs conservative normalization for obvious raw notes. By
+default, `PEOPLE_MEMORY_INGESTION_EXTRACTOR=llm` lets an OpenAI-compatible LLM
+propose structure first when LLM provider settings are available; without those
+settings, capture starts directly with deterministic normalization. Either way,
+the same identity policy, evidence preservation, and review rules still run.
+For example, `source_text` alone can capture simple patterns such as:
+
+- `Met Alice Zhang at Blue Bottle. We discussed robotics hiring. Alice mentioned Bob.`
+- `Remember Alice Zhang. Alice works at Tencent Robotics as product lead. Alice studied at Tsinghua. Email alice@example.com.`
+- `在Blue Bottle见了Alice Zhang，聊了robotics hiring，Alice Zhang提到Henry Guo。`
+- `今天在潘家园见了胡八一（胖子），聊了北京的项目。胖子提到王凯。`
+
+The harness should still pass structured fields when it has them, but it does
+not need to interrupt the user just to fill a form.
+
+Important modeling rules:
+
+- Put people who were present in `participants`.
+- Put people discussed but not present in `mentioned_people`.
+- Store "A said B ..." in `attributed_claims`, not as a direct fact about B.
+- Store relationship phrases such as "A knows B", "A works with B", or
+  "A introduced me to B" in `relationships`. If B is not already known, the
+  service creates a provisional second-degree card and returns a non-blocking
+  enrichment item.
+- Preserve Chinese names and aliases exactly. Explicit alias forms such as
+  `胡八一（胖子）`, `胡八一又叫胖子`, and `胡八一绰号胖子` are modeled as one
+  canonical person with `胖子` as an alias unless the server returns an identity
+  review because the alias already points to a different card.
+- Store promises and next actions in `follow_ups`.
+- Preserve sensitivity labels when the user marks something private, sensitive,
+  secondhand, unverified, or not to surface unprompted.
+
+Output fields that matter for harness autonomy:
+
+- `capture_summary`: a short structured checkpoint the harness should show the
+  user after saving, including people created/updated, key details, follow-ups,
+  review items, and a correction hint.
+- `captured_follow_ups`: follow-ups preserved from the capture.
+- `post_capture_opportunities`: a structured list of useful next actions the
+  harness may take after capture.
+- `harness_context_requests`: suggested ways for the harness to use its own
+  memory or available tools to enrich the result.
+- `needs_review`: ambiguity or data-quality items that should be handled
+  carefully rather than silently auto-merged.
+
+`post_capture_opportunities` include `recommended_default`, `risk_level`,
+`reversibility`, `external_visibility`, `requires_confirmation`, `undo_hint`,
+related people, and evidence. A harness should proactively execute low-risk,
+private/local, easily reversible opportunities when supported, then report what
+it did and how to undo it. It should ask first before externally visible,
+costly, destructive, privacy-sensitive, or hard-to-reverse actions such as
+sending messages, inviting other people to calendar events, merging ambiguous
+identities, deleting data, or publishing information.
+
+The harness should show the `capture_summary` every time because it is the
+fastest way for the user to catch mistakes immediately, such as "this was a
+different Alice", "that follow-up is wrong", or "remove that sensitive note".
+
+## retrieve_network_context
+
+Use for vague recall, relationship questions, and pre-meeting briefs.
+
+Input:
+
+- `query`: required natural-language query.
+- `limit`: optional result limit from 1 to 50, default 10.
+- `include_sensitive`: optional override. Use `true` to force sensitive facts
+  into the response, `false` to force-hide them, or omit it to use policy.
+- `sensitivity_policy`: optional `personal`, `strict`, or `task_aware`.
+  The default app policy is `personal` because this V1 is a single-user private
+  memory tool.
+- `output_context`: `private` or `shareable`, default `private`. In
+  `task_aware` mode, sensitive facts are included only for private recall and
+  hidden for shareable drafts or messages.
+- `mode`: `recall` or `brief`.
+
+Every result should include evidence, confidence-bearing source notes, and
+`why_matched`.
+
+Sensitivity labels are still preserved as metadata. They control surfacing
+policy; they do not delete or weaken the underlying memory.
+
+Harness integration guidance:
+
+- Treat this tool as the source of truth for people/network memory: social
+  notes, relationships, claims, follow-ups, and person-card facts.
+- Treat the AI harness's own memory as the source of truth for user-level
+  preferences, work style, current projects, and prior instructions.
+- Retrieve from this tool first, then let the harness combine the returned
+  evidence with its own user memory to curate the final answer.
+- If tool evidence and harness memory conflict about a person or interaction,
+  prefer the tool evidence for social facts and mention uncertainty only when it
+  affects the answer.
+- If the tool has no matching evidence, the harness may still use its own user
+  memory, but it should clearly separate that inference from social-graph
+  recall.
+- For task curation, such as dinner planning or intro drafting, retrieve with
+  the user's full task constraints, optionally call `get_person` for shortlisted
+  candidates, then explain recommendations using both source-backed social
+  evidence and user-preference context.
+
+The deterministic harness integration eval checks this behavior without
+requiring a live AI harness:
+
+```powershell
+people-memory eval-harness-integration --output .people-network-memory/harness-integration-eval.json
+```
+
+The eval report includes the prompt, simulated harness memory, MCP tool calls,
+actual retrieval results, hydrated person cards, and source-boundary checks for
+each case.
+
+## get_person
+
+Use when the caller already has a stable `person_id`, usually after retrieval.
+The tool also accepts `name` as a best-effort harness fallback because some AI
+harnesses may ask for a card by visible person name after capture or recall.
+When both are available, prefer `person_id`.
+
+The response returns either a full person card with `found: true`, or a small
+missing response with `found: false` and `missing_info`.

package/harness_adapters/openclaw/mcp.managed.unix.template.json

@@ -0,0 +1,25 @@
+{
+  "mcpServers": {
+    "people-network-memory": {
+      "command": "python3",
+      "args": [
+        "__REPO_ROOT__/scripts/people_memory_bootstrap.py",
+        "run",
+        "--repo",
+        "__REPO_ROOT__",
+        "--venv",
+        "__REPO_ROOT__/.venv",
+        "--backend",
+        "local_json",
+        "--extra",
+        "base"
+      ],
+      "env": {
+        "PEOPLE_MEMORY_BACKEND": "local_json",
+        "PEOPLE_MEMORY_INGESTION_EXTRACTOR": "llm",
+        "PEOPLE_MEMORY_SENSITIVITY_POLICY": "personal",
+        "GRAPHITI_TELEMETRY_ENABLED": "false"
+      }
+    }
+  }
+}

package/harness_adapters/openclaw/mcp.managed.windows.template.json

@@ -0,0 +1,26 @@
+{
+  "mcpServers": {
+    "people-network-memory": {
+      "command": "py",
+      "args": [
+        "-3.11",
+        "__REPO_ROOT__\\scripts\\people_memory_bootstrap.py",
+        "run",
+        "--repo",
+        "__REPO_ROOT__",
+        "--venv",
+        "__REPO_ROOT__\\.venv",
+        "--backend",
+        "local_json",
+        "--extra",
+        "base"
+      ],
+      "env": {
+        "PEOPLE_MEMORY_BACKEND": "local_json",
+        "PEOPLE_MEMORY_INGESTION_EXTRACTOR": "llm",
+        "PEOPLE_MEMORY_SENSITIVITY_POLICY": "personal",
+        "GRAPHITI_TELEMETRY_ENABLED": "false"
+      }
+    }
+  }
+}

package/harness_adapters/openclaw/mcp.template.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "people-network-memory": {
+      "command": "python",
+      "args": ["scripts/people_memory_bootstrap.py", "run", "--repo", ".", "--venv", ".venv"],
+      "env": {
+        "PEOPLE_MEMORY_BACKEND": "local_json",
+        "PEOPLE_MEMORY_INGESTION_EXTRACTOR": "llm",
+        "PEOPLE_MEMORY_SENSITIVITY_POLICY": "personal",
+        "GRAPHITI_TELEMETRY_ENABLED": "false"
+      }
+    }
+  }
+}