@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/harness_adapters/openclaw/installer.py

@@ -0,0 +1,577 @@
+"""OpenClaw install helpers.
+
+This module owns filesystem writes for the OpenClaw adapter. Product logic stays
+outside this layer; the installer only materializes MCP config and skill text.
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from people_network_memory.ports.errors import HarnessInstallError
+
+
+SERVER_ID = "people-network-memory"
+SKILL_DIR_NAME = "ppl"
+LEGACY_SKILL_DIR_NAMES = ("people-network-memory",)
+WORKSPACE_GUIDANCE_START = "<!-- people-network-memory:start -->"
+WORKSPACE_GUIDANCE_END = "<!-- people-network-memory:end -->"
+
+OPENCLAW_WORKSPACE_GUIDANCE = f"""{WORKSPACE_GUIDANCE_START}
+## People Network Memory MCP
+
+For requests about remembering, recording, recalling, or showing information about people, social interactions, person cards, relationships, introductions, meetings, dinners, coffee chats, calls, follow-ups, or who knows whom, use the `people-network-memory` MCP server before OpenClaw file memory.
+
+Explicit trigger:
+- If the user starts a prompt with `/ppl`, `/people_network_memory`, or `/people-network-memory`, treat that as an explicit request to use this MCP server. Remove only that trigger prefix before saving `source_text`; preserve the rest of the user's wording exactly.
+
+Priority rules:
+- Use `people-network-memory__record_interaction` for capture prompts such as "remember", "met", "spoke with", "had coffee", "had dinner", "add this person", "记一下", "见了", "认识了", or any new social note.
+- Use `people-network-memory__get_person` for person-card requests.
+- Use `people-network-memory__retrieve_network_context` for vague recall, relationship questions, and pre-meeting briefs.
+- Do not satisfy people/network memory requests by only reading or writing `MEMORY.md`, `memory/YYYY-MM-DD.md`, or other files.
+- Do not use `read`, `write`, `edit`, or `exec` as a substitute for the people-network-memory MCP tools.
+- If you also update OpenClaw memory files, do it only after the MCP tool succeeds and report that file update as a secondary reversible action.
+- If the MCP tool is unavailable or fails, say that the people-network-memory MCP lookup/save failed and include the tool error instead of pretending the file memory is the source of truth.
+{WORKSPACE_GUIDANCE_END}"""
+
+SKILL_MARKDOWN = """---
+name: "ppl"
+description: "Use when users want to remember people, record social interactions, recall vague personal-network context, or prepare a pre-meeting brief."
+---
+
+# People Network Memory
+
+## Goal
+
+Help the user record and recall social memory with low friction. Treat messy notes as capture tasks, not as forms.
+
+## Tool Routing
+
+- If the user starts a prompt with `/ppl`, `/people_network_memory`, or `/people-network-memory`, treat that as an explicit request to use this skill and its MCP tools. Remove only that trigger prefix before saving `source_text`; preserve the rest of the user's wording exactly.
+- This skill's tools are MCP tools. In OpenClaw they may appear as `people-network-memory__record_interaction`, `people-network-memory__retrieve_network_context`, and `people-network-memory__get_person`. Do not call a tool named `ppl` or `people-network-memory`; `ppl` is the skill name and `people-network-memory` is the MCP server namespace, not a callable tool.
+- The people/network graph is the source of truth for people, interactions, relationships, claims, follow-ups, and person cards. Do not satisfy a people-memory request by only reading or writing OpenClaw `MEMORY.md`, daily notes, or other files.
+- Never use OpenClaw `read`, `write`, or `edit` as a substitute for the MCP tools. If you also update harness memory, do it only after the MCP tool succeeds, report it as a secondary reversible action, and keep MCP evidence as the source of truth.
+- Use `record_interaction` first when the user says "remember", "met", "spoke with", "had coffee/dinner/call", "add this person", or otherwise describes a meeting, dinner, coffee, call, event, intro, conversation, or new social note.
+- Do not call `get_person` first for a capture prompt just because a person's name appears. Capture the note with `record_interaction`, then call retrieval or `get_person` only if the user also asks for a card/brief.
+- Use `retrieve_network_context` for vague recall, relationship questions, and pre-meeting briefs.
+- Use `get_person` when the user asks for one person card by known ID, by visible name as a fallback, or after retrieval identifies a person.
+- For every person-card request, call `get_person` again even if the same card was shown earlier in the chat. Do not answer "same as above" from conversation memory unless `get_person` fails and you clearly say the MCP lookup failed.
+- If `get_person` returns `found=false` with `ambiguous=true` or a non-empty `candidates` list, do not choose one candidate or answer from only the first candidate. Present all candidates with their `person_id` and distinguishing details, then ask the user to clarify if needed.
+- If `retrieve_network_context` returns `ambiguous=true`, its `answer_policy` and `final_answer_instruction` are mandatory. Start by listing every candidate; never start with "yes", "no", or a single candidate answer. Use `candidate_results` to state candidate-specific evidence only after the ambiguity is shown.
+- For person-card requests, render the `get_person` JSON result directly inline in chat. Do not create a canvas/embed/browser page or ask the user to open a local URL unless the user explicitly asks for a visual UI.
+- If a canvas, browser, gateway, or hosted embed returns `Unauthorized`, retry with `get_person` or `retrieve_network_context` and present the card inline instead of returning the raw auth error.
+- Never call `record_interaction` to recreate or "fix" a memory just because retrieval looks incomplete. First retry retrieval with more specific constraints or call `get_person`; only record again when the user explicitly provides a new note to save or asks you to re-save it.
+
+## Capture Rules
+
+- Preserve the user's original wording in `source_text`.
+- Separate participants from mentioned people.
+- Store "A said B ..." as an attributed claim, not as a direct fact about B.
+- Store "A knows B", "A works with B", and "A introduced me to B" as relationships.
+- If a relationship names a new person who was not present, allow a provisional second-degree card and do not interrupt capture.
+- Include dates, places, topics, commitments, follow-ups, contact info, interests, and relationship assertions when visible.
+- Preserve Chinese names and aliases exactly. When the user writes an explicit alias such as `胡八一（胖子）`, `胡八一又叫胖子`, or `胡八一绰号胖子`, treat `胡八一` as the canonical display name and `胖子` as an alias unless the tool returns an identity review. Do not shorten names or remove visible prefixes such as `测试`.
+- Do not rewrite hard-to-parse Chinese notes before capture. Preserve `source_text`; the MCP may use a tool-side LLM extractor before deterministic validation.
+- For simple capture, the safest payload is only `{"source_text": "<the user's exact note>"}`. Add structured fields only when you are confident; the MCP can extract structure from `source_text`.
+- Do not interrupt simple capture. Ask only for high-impact ambiguity such as duplicate identity, unclear person reference, or sensitive secondhand claims.
+- Never invent missing personal facts.
+
+## Post-Capture Autonomy Rules
+
+- After every `record_interaction`, read the full response, especially `post_capture_opportunities`, `harness_context_requests`, `captured_follow_ups`, `needs_review`, and `evidence`.
+- Always show the user a brief capture summary after saving. Prefer the tool's `capture_summary` if present: people created/updated, key details, follow-ups, review items, and the correction hint.
+- The summary is a user-facing correction checkpoint, not a long report. Keep it short enough that the user can quickly spot wrong identities, wrong facts, or unwanted follow-ups.
+- When an existing person was updated, say so plainly, such as "Updated existing card: Alice Zhang." Add a quiet correction path: "If this was a different Alice, say 'different person'."
+- Use your own memory and available tools to proactively execute low-risk, private/local, easily reversible next steps when the response recommends `execute_if_supported`.
+- Examples: create a private reminder/task for an open loop, search harness memory for related people/events, draft but do not send a follow-up message, or prepare a private shortlist/context note.
+- For captured follow-ups, create a one-time reminder/task by default. Do not create a recurring reminder unless the user explicitly says the obligation repeats, such as weekly, every month, or every Monday.
+- Do not ask the user to choose between reminder mechanisms for a normal private follow-up. Pick the lowest-friction reversible local option available: timed notification first, then one-time task/reminder, then private task-list item.
+- Do not ask "should I set a reminder?" when `post_capture_opportunities` says `recommended_default=execute_if_supported`, `requires_confirmation=false`, and the action is private/reversible. Execute the reminder/task if a suitable tool exists, then report `Action`, `Why`, and `Undo`.
+- If no reminder/task tool exists, say you could not create the reminder because no suitable tool is available. Do not ask for permission before discovering whether a suitable private reminder mechanism exists.
+- If the harness only exposes cron-style reminders, still make one-off follow-ups self-expiring when the tool supports it; otherwise clearly say the reminder is recurring and ask before creating it.
+- Report every autonomous action you took with `Action:`, `Why:`, and `Undo:`. If you cannot name the exact undo command, explain the safest practical undo path, such as deleting the reminder/task or asking you to remove it.
+- Ask before actions that are externally visible, irreversible or hard to reverse, privacy-sensitive, costly, or destructive, such as sending messages, creating calendar invites with other people, merging ambiguous identities, deleting data, or publishing/sharing information.
+- If opportunity time hints are vague, use a reasonable private reminder default when the action is reversible; ask only when the timing materially matters.
+
+## Retrieval Rules
+
+- Use retrieval before answering from memory.
+- Return evidence: source note, date, speaker attribution, and why the result matched.
+- Default private recall may include sensitive context because this is a single-user memory tool.
+- Use `sensitivity_policy="task_aware"` and `output_context="shareable"` when drafting messages, intros, emails, or anything that may be shown to others.
+- Use `sensitivity_policy="strict"` when the user asks for a privacy-safe summary.
+- Treat `retrieve_network_context` results as an evidence pack, not as a finished answer.
+- Prefer the tool's ranked order, because the tool may already have used deterministic rules plus an optional tool-side LLM judge to rerank candidates.
+- Do not use the harness model's general memory to override source-backed tool results. If the tool evidence is weak or conflicting, say so.
+- For "who mentioned X" queries, answer with the speaker or source person who mentioned X, not X unless the evidence says X mentioned themself.
+- For follow-up or promise queries, prioritize results whose kind is `follow_up`; do not answer from a loosely related person fact.
+- For profile-style queries with multiple constraints, prefer results that satisfy all constraints on the same person, such as company plus topic.
+- When several people genuinely match, present a short ranked shortlist with reasons instead of pretending there is only one answer.
+- For exact-name questions where multiple person cards share the same display name, preserve the ambiguity and list every matching card. A familiar alias from earlier chat or a richer profile match is not enough to collapse a full-name query to one person; do not say "you probably mean" one candidate.
+- For ambiguous yes/no questions, do not answer "yes" or "no" globally. Say which candidate has the supporting evidence and which candidate has no matching evidence.
+- If the result includes `needs_review`, `missing_info`, low confidence, or ambiguous identity, surface that uncertainty briefly.
+- If expected people are missing from retrieval, do not reconstruct and re-record them from chat context or OpenClaw file memory. Say the MCP result looks incomplete, retry with a narrower query, and ask before saving any duplicate note.
+
+## Harness Reasoning Rules
+
+- Use the harness LLM after retrieval to synthesize, compare, and curate answers for the user's current task.
+- Treat this MCP as the source of truth for the user's people/network memory: people, interactions, relationships, claims, follow-ups, preferences about other people, and evidence from social notes.
+- Treat the harness's own memory as the source of truth for the user's stable preferences, working style, current projects, communication style, constraints, and prior instructions.
+- Combine both memory sources deliberately: first retrieve people/network context from this MCP, then apply the harness's user-memory context to decide what is useful, tactful, timely, or aligned with the user's goals.
+- If the harness memory and MCP evidence conflict about a person or interaction, prefer MCP evidence for social-memory facts and mention the conflict briefly if it matters.
+- If the MCP has no evidence about a person but the harness remembers user-level context that helps the task, say the social graph has no matching evidence and clearly separate the harness-memory-based inference.
+- For planning tasks such as dinner groups, intros, meeting prep, hiring help, or outreach, call `retrieve_network_context` with the user's full task constraints, then reason over the returned evidence.
+- When choosing people for a task, explain each recommendation using source-backed factors such as relationship, location, interests, recent interactions, open follow-ups, and mutual connections.
+- Call `get_person` for shortlisted people when the answer needs fuller card details, work history, education, contact info, preferences, or relationship context.
+- Separate direct facts from attributed claims in the final answer. Phrase claims as "Alice said..." or "according to the note..." unless confirmed elsewhere.
+- Keep private answers useful and direct. For shareable drafts, omit sensitive or secondhand context unless the user explicitly asks to include it.
+- If retrieval returns no useful evidence, say that the memory graph does not have enough information and ask one concise follow-up question only when it would unblock the task.
+
+## Examples
+
+User: "Met Alice at Blue Bottle. We talked about robotics hiring. Alice said Bob may leave Tencent. I promised to send Alice two founder contacts next week."
+
+First use `record_interaction` (`people-network-memory__record_interaction` if OpenClaw shows namespaced MCP tools) with Alice as participant, Bob as mentioned person, robotics hiring as topic, the Bob note as an attributed claim from Alice, and the founder-contact promise as a follow-up. Do not write this only to OpenClaw memory files. Then show a brief capture summary from `capture_summary`, including created/updated people and the correction hint. Inspect `post_capture_opportunities`: if a private reminder/task tool is available, create a reversible reminder for the founder-contact promise and report it with `Action:`, `Why:`, and `Undo:`; search harness memory for related founder contacts if useful; draft but do not send any message without confirmation. Only after that, use `retrieve_network_context` or `get_person` if the user asks for recall, a brief, or a card.
+
+User: "Who was the robotics person I met at the coffee shop?"
+
+Use `retrieve_network_context` with the original vague query.
+
+User: "Brief me before I meet Alice."
+
+Use `retrieve_network_context` with `mode="brief"` and include recent interactions, open follow-ups, claims, and relationship context.
+
+User: "Show me Alice Zhang's person card."
+
+Use `get_person` (`people-network-memory__get_person` if OpenClaw shows namespaced MCP tools) with Alice's name or stable `person_id`, then format the returned card inline in the chat. Do not use canvas, browser, hosted embeds, local URLs, or OpenClaw memory files for the default card view.
+
+User: "Plan a dinner in Shanghai for five people who would enjoy robotics and founder intros."
+
+Use `retrieve_network_context` with the full task as the query. Shortlist candidates from the ranked results, call `get_person` for any unclear top candidates, then combine the MCP evidence with the harness's memory of the user's preferences, budget, style, current goals, and constraints. Recommend the group with evidence-backed reasons and note any uncertainty.
+"""
+
+
+@dataclass(frozen=True)
+class OpenClawInstallResult:
+    ok: bool
+    dry_run: bool
+    home: str
+    mcp_json: str
+    openclaw_config: str | None
+    skill_path: str
+    workspace_guidance_path: str
+    server_action: Literal["created", "updated", "unchanged"]
+    skill_action: Literal["created", "updated", "unchanged"]
+    workspace_guidance_action: Literal["created", "updated", "unchanged"]
+    mcp_entry: dict[str, Any]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "dry_run": self.dry_run,
+            "home": self.home,
+            "mcp_json": self.mcp_json,
+            "openclaw_config": self.openclaw_config,
+            "skill_path": self.skill_path,
+            "workspace_guidance_path": self.workspace_guidance_path,
+            "server_action": self.server_action,
+            "skill_action": self.skill_action,
+            "workspace_guidance_action": self.workspace_guidance_action,
+            "mcp_entry": self.mcp_entry,
+        }
+
+
+@dataclass(frozen=True)
+class OpenClawCheck:
+    name: str
+    ok: bool
+    detail: str
+    remediation: str | None = None
+
+    def to_json(self) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "name": self.name,
+            "ok": self.ok,
+            "detail": self.detail,
+        }
+        if self.remediation:
+            payload["remediation"] = self.remediation
+        return payload
+
+
+def install_openclaw_adapter(
+    *,
+    home: str | Path,
+    command: str | None = None,
+    command_args: list[str] | None = None,
+    backend: str = "local_json",
+    ingestion_extractor: str = "llm",
+    identity_advisor: str = "llm",
+    managed_bootstrap: bool = False,
+    auto_update: bool = False,
+    dry_run: bool = False,
+) -> OpenClawInstallResult:
+    resolved_home = Path(home).expanduser()
+    mcp_path = resolved_home / "mcp.json"
+    openclaw_config_path = resolved_home / "openclaw.json"
+    skill_path = resolved_home / "skills" / SKILL_DIR_NAME / "SKILL.md"
+    workspace_guidance_path = resolved_home / "workspace" / "AGENTS.md"
+    mcp_data = _load_or_initialize_mcp_json(mcp_path)
+    mcp_servers = _mcp_servers(mcp_data, mcp_path)
+    openclaw_data = None
+    openclaw_servers = None
+    if openclaw_config_path.exists():
+        openclaw_data = _load_or_initialize_openclaw_json(openclaw_config_path)
+        openclaw_servers = _openclaw_mcp_servers(openclaw_data, openclaw_config_path)
+
+    entry = build_mcp_entry(
+        command=command,
+        command_args=command_args,
+        backend=backend,
+        ingestion_extractor=ingestion_extractor,
+        identity_advisor=identity_advisor,
+        managed_bootstrap=managed_bootstrap,
+        auto_update=auto_update,
+    )
+    existing_entry = mcp_servers.get(SERVER_ID)
+    merged_entry = _merge_entry(existing_entry, entry)
+    legacy_action = _entry_action(existing_entry, merged_entry)
+    mcp_servers[SERVER_ID] = merged_entry
+    server_action = legacy_action
+    if openclaw_servers is not None:
+        existing_openclaw_entry = openclaw_servers.get(SERVER_ID)
+        openclaw_entry = _merge_entry(existing_openclaw_entry, entry)
+        server_action = _entry_action(existing_openclaw_entry, openclaw_entry)
+        openclaw_servers[SERVER_ID] = openclaw_entry
+        merged_entry = openclaw_entry
+
+    existing_skill = skill_path.read_text(encoding="utf-8") if skill_path.exists() else None
+    if existing_skill is None:
+        skill_action: Literal["created", "updated", "unchanged"] = "created"
+    elif existing_skill == SKILL_MARKDOWN:
+        skill_action = "unchanged"
+    else:
+        skill_action = "updated"
+    existing_guidance = (
+        workspace_guidance_path.read_text(encoding="utf-8")
+        if workspace_guidance_path.exists()
+        else None
+    )
+    updated_guidance = _upsert_managed_workspace_guidance(existing_guidance)
+    if existing_guidance is None:
+        workspace_guidance_action: Literal["created", "updated", "unchanged"] = "created"
+    elif existing_guidance == updated_guidance:
+        workspace_guidance_action = "unchanged"
+    else:
+        workspace_guidance_action = "updated"
+
+    if not dry_run:
+        resolved_home.mkdir(parents=True, exist_ok=True)
+        mcp_path.write_text(
+            json.dumps(mcp_data, ensure_ascii=False, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+        if openclaw_data is not None:
+            openclaw_config_path.write_text(
+                json.dumps(openclaw_data, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+        skill_path.parent.mkdir(parents=True, exist_ok=True)
+        skill_path.write_text(SKILL_MARKDOWN, encoding="utf-8")
+        _remove_legacy_skill_dirs(resolved_home)
+        workspace_guidance_path.parent.mkdir(parents=True, exist_ok=True)
+        workspace_guidance_path.write_text(updated_guidance, encoding="utf-8")
+
+    return OpenClawInstallResult(
+        ok=True,
+        dry_run=dry_run,
+        home=str(resolved_home),
+        mcp_json=str(mcp_path),
+        openclaw_config=str(openclaw_config_path) if openclaw_config_path.exists() else None,
+        skill_path=str(skill_path),
+        workspace_guidance_path=str(workspace_guidance_path),
+        server_action=server_action,
+        skill_action=skill_action,
+        workspace_guidance_action=workspace_guidance_action,
+        mcp_entry=merged_entry,
+    )
+
+
+def openclaw_checks(home: str | Path) -> list[OpenClawCheck]:
+    resolved_home = Path(home).expanduser()
+    mcp_path = resolved_home / "mcp.json"
+    openclaw_config_path = resolved_home / "openclaw.json"
+    skill_path = resolved_home / "skills" / SKILL_DIR_NAME / "SKILL.md"
+    workspace_guidance_path = resolved_home / "workspace" / "AGENTS.md"
+    checks = [
+        OpenClawCheck(
+            name="openclaw_home",
+            ok=resolved_home.exists(),
+            detail=str(resolved_home),
+            remediation="Run `people-memory install-openclaw` or create the OpenClaw home directory.",
+        )
+    ]
+    try:
+        if openclaw_config_path.exists():
+            mcp_data = _load_or_initialize_openclaw_json(openclaw_config_path)
+            mcp_servers = _openclaw_mcp_servers(mcp_data, openclaw_config_path)
+            config_path = openclaw_config_path
+        else:
+            mcp_data = _load_or_initialize_mcp_json(mcp_path)
+            mcp_servers = _mcp_servers(mcp_data, mcp_path)
+            config_path = mcp_path
+        entry = mcp_servers.get(SERVER_ID)
+        checks.append(
+            OpenClawCheck(
+                name="openclaw_mcp_server",
+                ok=entry is not None,
+                detail=str(config_path) if entry is not None else f"{SERVER_ID} missing in {config_path}",
+                remediation="Run `people-memory install-openclaw`.",
+            )
+        )
+    except HarnessInstallError as exc:
+        checks.append(
+            OpenClawCheck(
+                name="openclaw_mcp_server",
+                ok=False,
+                detail=str(exc),
+                remediation="Fix or replace the OpenClaw mcp.json file.",
+            )
+        )
+    checks.append(
+        OpenClawCheck(
+            name="openclaw_skill",
+            ok=skill_path.exists(),
+            detail=str(skill_path) if skill_path.exists() else f"missing {skill_path}",
+            remediation="Run `people-memory install-openclaw`.",
+        )
+    )
+    guidance_ok = False
+    if workspace_guidance_path.exists():
+        guidance = workspace_guidance_path.read_text(encoding="utf-8")
+        guidance_ok = WORKSPACE_GUIDANCE_START in guidance and WORKSPACE_GUIDANCE_END in guidance
+    checks.append(
+        OpenClawCheck(
+            name="openclaw_workspace_guidance",
+            ok=guidance_ok,
+            detail=(
+                str(workspace_guidance_path)
+                if guidance_ok
+                else f"missing managed guidance in {workspace_guidance_path}"
+            ),
+            remediation="Run `people-memory install-openclaw`.",
+        )
+    )
+    return checks
+
+
+def build_mcp_entry(
+    *,
+    command: str | None = None,
+    command_args: list[str] | None = None,
+    backend: str = "local_json",
+    ingestion_extractor: str = "llm",
+    identity_advisor: str = "llm",
+    managed_bootstrap: bool = False,
+    auto_update: bool = False,
+) -> dict[str, Any]:
+    env = _base_env(
+        backend=backend,
+        ingestion_extractor=ingestion_extractor,
+        identity_advisor=identity_advisor,
+    )
+    if managed_bootstrap:
+        resolved_command, resolved_args = _managed_bootstrap_command(
+            backend=backend,
+            auto_update=auto_update,
+            command=command,
+            command_args=command_args,
+        )
+        return {
+            "command": resolved_command,
+            "args": resolved_args,
+            "env": env,
+        }
+    resolved_command = command or sys.executable
+    resolved_args = command_args if command_args is not None else _default_command_args(resolved_command)
+    return {
+        "command": resolved_command,
+        "args": resolved_args,
+        "env": env,
+    }
+
+
+def _base_env(
+    *, backend: str, ingestion_extractor: str, identity_advisor: str
+) -> dict[str, str]:
+    env = {
+        "PEOPLE_MEMORY_BACKEND": backend,
+        "PEOPLE_MEMORY_INGESTION_EXTRACTOR": ingestion_extractor,
+        "PEOPLE_MEMORY_IDENTITY_ADVISOR": identity_advisor,
+        "PEOPLE_MEMORY_SENSITIVITY_POLICY": "personal",
+        "GRAPHITI_TELEMETRY_ENABLED": "false",
+    }
+    return env
+
+
+def _load_or_initialize_mcp_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"mcpServers": {}}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise HarnessInstallError(f"Invalid JSON in {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise HarnessInstallError(f"{path} must contain a JSON object.")
+    payload.setdefault("mcpServers", {})
+    return payload
+
+
+def _load_or_initialize_openclaw_json(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise HarnessInstallError(f"Invalid JSON in {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise HarnessInstallError(f"{path} must contain a JSON object.")
+    mcp = payload.setdefault("mcp", {})
+    if not isinstance(mcp, dict):
+        raise HarnessInstallError(f"{path} field `mcp` must be an object.")
+    mcp.setdefault("servers", {})
+    return payload
+
+
+def _mcp_servers(payload: dict[str, Any], path: Path) -> dict[str, Any]:
+    servers = payload.get("mcpServers")
+    if not isinstance(servers, dict):
+        raise HarnessInstallError(f"{path} field `mcpServers` must be an object.")
+    return servers
+
+
+def _openclaw_mcp_servers(payload: dict[str, Any], path: Path) -> dict[str, Any]:
+    mcp = payload.get("mcp")
+    if not isinstance(mcp, dict):
+        raise HarnessInstallError(f"{path} field `mcp` must be an object.")
+    servers = mcp.get("servers")
+    if not isinstance(servers, dict):
+        raise HarnessInstallError(f"{path} field `mcp.servers` must be an object.")
+    return servers
+
+
+def _entry_action(existing: Any, merged: dict[str, Any]) -> Literal["created", "updated", "unchanged"]:
+    if existing is None:
+        return "created"
+    if existing == merged:
+        return "unchanged"
+    return "updated"
+
+
+def _merge_entry(existing: Any, desired: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(existing, dict):
+        return desired
+    merged = dict(existing)
+    existing_env = existing.get("env") if isinstance(existing.get("env"), dict) else {}
+    desired_env = desired.get("env", {})
+    merged.update({"command": desired["command"], "args": desired["args"]})
+    merged["env"] = {**existing_env, **desired_env}
+    return merged
+
+
+def _upsert_managed_workspace_guidance(existing: str | None) -> str:
+    base = existing or "# AGENTS.md - Your Workspace\n"
+    block = OPENCLAW_WORKSPACE_GUIDANCE.strip()
+    start_index = base.find(WORKSPACE_GUIDANCE_START)
+    end_index = base.find(WORKSPACE_GUIDANCE_END)
+    if start_index != -1 and end_index != -1 and end_index > start_index:
+        end_index += len(WORKSPACE_GUIDANCE_END)
+        updated = base[:start_index].rstrip() + "\n\n" + block + "\n\n" + base[end_index:].lstrip()
+        return updated
+    lines = base.splitlines()
+    if lines and lines[0].lstrip().startswith("#"):
+        tail = lines[1:]
+        while tail and not tail[0].strip():
+            tail = tail[1:]
+        inserted = [lines[0], "", block, "", *tail]
+        return "\n".join(inserted).rstrip() + "\n"
+    return block + "\n\n" + base.rstrip() + "\n"
+
+
+def _remove_legacy_skill_dirs(home: Path) -> None:
+    skills_root = home / "skills"
+    for legacy_name in LEGACY_SKILL_DIR_NAMES:
+        if legacy_name == SKILL_DIR_NAME:
+            continue
+        legacy_dir = skills_root / legacy_name
+        legacy_skill = legacy_dir / "SKILL.md"
+        if not legacy_skill.exists():
+            continue
+        try:
+            text = legacy_skill.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        if not _looks_like_managed_people_skill(text):
+            continue
+        legacy_skill.unlink()
+        try:
+            legacy_dir.rmdir()
+        except OSError:
+            pass
+
+
+def _looks_like_managed_people_skill(text: str) -> bool:
+    return (
+        'name: "people-network-memory"' in text
+        and "This skill's tools are MCP tools" in text
+        and "people-network-memory__record_interaction" in text
+    )
+
+
+def _default_command_args(command: str) -> list[str]:
+    command_name = Path(command).name.lower()
+    if command_name in {"people-memory", "people-memory.exe"}:
+        return ["start"]
+    return ["-m", "people_network_memory.cli", "start"]
+
+
+def _managed_bootstrap_command(
+    *,
+    backend: str,
+    auto_update: bool,
+    command: str | None,
+    command_args: list[str] | None,
+) -> tuple[str, list[str]]:
+    repo_root = Path(__file__).resolve().parents[4]
+    bootstrap_script = repo_root / "scripts" / "people_memory_bootstrap.py"
+    if command:
+        resolved_command = command
+        resolved_args = list(command_args or [])
+    elif platform.system().lower().startswith("win"):
+        resolved_command = "py"
+        resolved_args = ["-3.11"]
+    else:
+        resolved_command = "python3"
+        resolved_args = []
+    extra = "graphiti" if backend == "graphiti" else "base"
+    resolved_args.extend(
+        [
+            str(bootstrap_script),
+            "run",
+            "--repo",
+            str(repo_root),
+            "--venv",
+            str(repo_root / ".venv"),
+            "--backend",
+            backend,
+            "--extra",
+            extra,
+        ]
+    )
+    if auto_update:
+        resolved_args.append("--git-pull")
+    return resolved_command, resolved_args