# Install PersonOS Context for this AI

Use this guide only after the user asks to connect PersonOS Context. The connection endpoint is **https://www.personosai.com/api/mcp**. The versioned installation manifest is [manifest.json](https://www.personosai.com/connect/manifest.json).

## Choose the host

Read the manifest and select the host the user named. If the current host is known, use it. Do not install every host, replace another server, create an invented marketplace entry, or assume access to the user's computer from a cloud chat. Each host entry contains its supported method, real configuration path, official documentation, authentication steps and copyable commands. `documentation_checked` describes our evidence; it does not claim a successful connection on this machine.

For a cloud-only host, guide the user through its custom remote connector UI. For a local host with file or command access, perform the configuration directly. If a required tool, account entitlement or runtime is missing, report that specific missing prerequisite.

## Install

1. Inspect only the chosen host's MCP configuration. Preserve existing servers and settings; do not read credential stores or print unrelated configuration values. Respect an explicitly configured custom path or active host profile. The listed home-directory paths are defaults.
2. Use the host's native command when provided. Otherwise download [install.py](https://www.personosai.com/connect/install.py), inspect it, then run `python3 install.py --host HOST_ID --dry-run`. After checking the proposed path, run the same command with `--apply`. VS Code requires an explicit `--workspace` or `--config`; Cline IDE users should supply the path opened by the MCP settings UI. The script supports strict JSON only, makes a private backup and refuses conflicting existing values. For JSONC, JSON5, YAML or TOML, use the host UI or a format-aware incremental edit with a backup; do not rewrite the whole file from a sample.
3. A native plugin is an alternative to a direct MCP entry. Do not install both for the same server. The manifest's package URLs point to real release ZIP files under `https://www.personosai.com/assets/downloads/`. Use `python3 install.py --package PACKAGE_ID --dry-run`, then `--apply` to download, check the manifest's SHA-256 and stage the package. This does not yet install it in the host. Run the host's documented plugin/extension install command against the returned `packagePath`. The downloaded directory contains the manifests at its root. Do not run scripts from the archive or invent a registry/package-manager command.
4. Reload the MCP connection or start a new chat if the host needs it. Do not stop an active Gateway or restart a whole application without checking whether it would interrupt the user's work.

## Let the user authorize

Start the host's OAuth flow and let the user approve in their browser. Do not ask them to paste passwords or tokens into the chat. If an OAuth configuration UI offers registration options, choose **Register automatically** for PersonOS; do not invent a client ID or secret. Use the basic connection scopes offered by the service. Installation does not authorize historical imports, automatic memory, or broader write scopes.

The OAuth issuer is `https://www.personosai.com/api`. Its metadata is at `https://www.personosai.com/.well-known/oauth-authorization-server/api`; the MCP protected-resource metadata is at `https://www.personosai.com/.well-known/oauth-protected-resource/api/mcp`. Let the host use this discovery flow; do not reconstruct OAuth endpoint paths or route credentials through an apex-domain redirect.

For OpenClaw's default local Gateway at `127.0.0.1:18789` or `localhost:18789`, prefer Settings → MCP for OAuth. Other Gateway addresses need their exact callback registered by the service operator; do not assume a remote HTTPS Gateway is already accepted. The alternative `openclaw mcp login personos-context` requires an offline Gateway. Do not interrupt active work to stop it. In a shared Gateway, use per-requester identities rather than sharing one person's Context credentials. The documented Hermes path here is the local CLI: use `auth: oauth`, then `hermes mcp login personos-context` after adding the custom entry. Hermes Dashboard callbacks require separate exact registration by the service operator. PersonOS is not asserted to be in either host's built-in marketplace.

If the browser flow is unfinished, report **configured; awaiting authorization**. If this chat cannot see newly added tools, say a reload or new chat is required. Do not treat an archive download, successful config write, or visible server name as an authenticated connection.

## Verify without storing anything

List the tools and check the five names in `manifest.toolNames`: `context_recall`, `context_remember`, `context_status`, `context_read_source`, `context_result`. Prefixes added by the host are expected. Then call **context_status with an empty object** and inspect the returned scopes and write policy. This is the installation acceptance check. It must return a real service response; do not simulate it.

Do not call recall, read_source or result just to test installation. Do not call remember with a fictional fact or user preference. The installation request is not permission to store test content. A read/write demonstration can be performed later only after the user explicitly requests that separate action and supplies or approves the content.

Report the selected host, configured location or installed package, whether browser authorization completed, the actual tools seen, and the status response's write policy. Separate `configured`, `authorization_pending`, `tools_missing` and `connected`. If the service still exposes an older tool set, report a version mismatch rather than pretending the new tools worked.

## Use the connection

Recall when a task depends on saved preferences, previous decisions, commitments or project context. Remember concise useful information when the user explicitly asks to save it, or when a fresh service policy explicitly allows automatic memory for that scope. A successful installation alone grants no automatic-write permission. Preserve the user's exact evidence and distinguish user statements, quotations about someone else and assistant suggestions. The service's server instructions and tool schemas define the current behavior.

For application code, see the [OAuth and SDK examples](https://www.personosai.com/connect/examples/README.md). The examples use an access token obtained by your application's OAuth flow, never a local owner credential or a fabricated API key.