# Installing Multimem

Multimem is a folder of stdlib-only Python 3.9+ scripts. The same folder serves every host; `install --host …` registers it with one host at a time, idempotently, and `uninstall --host …` removes exactly what was written.

Before any of the blocks below: the Any desktop app is running and signed in (its server listens on `127.0.0.1:31330`), or you have a hand-started `any run` (`127.0.0.1:7001`). `MULTIMEM_ADDR=host:port` points at anything else.

## Choose the space first

- **Existing memory space:** verify and pin its server and space, then run `ensure` **without `--create`**. Follow the existing-space steps below.
- **Fresh space:** inspect the existing setup and get approval to create a space, then choose your host's fresh-install block. Only this path uses `ensure --create`.
- **Returning session:** use `context`, `search` and the session workflow. Do not reinstall or create another space.

Use `doctor` to inspect the connection, then pin the intended address and space id or exact name before `ensure`. Do not rely on implicit space selection for an existing setup.

## Use an existing memory space

Existing objects stay in their current space; the five core `mp.*` bundle identities are stable across this kit update.

### 1. Inspect and pin the destination

Use the installed kit, or download without registering a host:

```sh
curl -fsSL https://any.org/assets/multimem/get.py | python3 - --no-install
python3 ~/.multimem/kit/multimem.py --version
python3 ~/.multimem/kit/multimem.py doctor
```

The download-only default is `~/.multimem/kit/`. In the commands below, replace `<kit>` with the actual kit folder, and replace the destination placeholders with verified values. If `doctor` cannot find the intended space, inspect the app and its space list; do not create a replacement.

```sh
python3 <kit>/multimem.py config --set 'addr=<verified-host:port>'
python3 <kit>/multimem.py config --set 'space.id=<verified-space-id>'
python3 <kit>/multimem.py config
python3 <kit>/multimem.py doctor
```

You may pin `space.name=<verified-exact-name>` instead when that uniquely identifies the intended space. Inspect the effective config and the reported server and space before any space write; environment overrides must also point to the intended destination.

For a coding-memory upgrade, do not add `--pack brain` or `--preset life`. Check `packs` and `areas_preset` in the effective config: `ensure` also reconciles configured packs and packs already installed in the space. Omitting flags does not disable them. The supplied `config.example.json` enables **brain/life**; it is not a neutral upgrade template.

### 2. Register the hosts you use

Run `python3 <kit>/multimem.py install --host claude-code` or `python3 <kit>/multimem.py install --host codex` for the hosts you actually use. These operations refresh the kit's registration and preserve unrelated settings.

Claude Code copies the kit into `~/.claude/skills/multimem/`. If you use both hosts, run the Codex installation from that folder to share one kit. Open `/hooks` inside Codex to trust its hooks. For MCP-only or rules-only hosts, use their registration options below with the existing-space path, without creating a new space.

### 3. Adopt and verify

Run from the kit folder now registered with your host:

```sh
python3 <kit>/multimem.py ensure
python3 <kit>/multimem.py doctor
```

Do not add `--create`. Check that the report identifies the verified server and existing space. The core bundles are adopted, options are reconciled, and kit files are attached to the handbook. A repeat run should report unchanged files when their bytes have not changed. `ensure` keeps existing nonempty handbook text; `handbook push` replaces it and renames the page, so run that separately only if the user approves.

Start a fresh Claude Code session and a fresh Codex session for the hosts installed. Check the first-turn `<multimem>` digest and new `session-start ok` / `prompt ok` entries in `~/.multimem/hooks.log`. In Codex, confirm `multimem_context` is available after trusting the hooks. In the new session's working directory, `python3 <kit>/multimem.py session current` should show the session key cached by its hook.

Report the changed local files, intended server and space, adoption result, any optional handbook update, and which fresh-session checks actually passed.

## Fresh-space host installation

The following host blocks are for an explicitly approved **new** space. For an existing space, use the path above instead.

## Claude Code

```sh
curl -fsSL https://any.org/assets/multimem/get.py | python3 - --host claude-code
python3 ~/.claude/skills/multimem/multimem.py ensure --create
python3 ~/.claude/skills/multimem/multimem.py doctor
```

What that does: downloads the kit into `~/.claude/skills/multimem/` (the `multimem` skill), registers five hooks in `~/.claude/settings.json` (SessionStart, UserPromptSubmit, PostToolUse on file writes, Stop, SessionEnd), creates the `Multimem` space and installs the schema. Start a new Claude Code session: the context digest arrives in the first turn as a `<multimem>` block.

Already have the kit somewhere? `python3 <kit>/multimem.py install --host claude-code` copies it into the skill folder and registers the hooks.

Remove: `python3 ~/.claude/skills/multimem/multimem.py uninstall --host claude-code`.

## Codex (CLI and desktop app)

```sh
curl -fsSL https://any.org/assets/multimem/get.py | python3 - --host codex
python3 ~/.multimem/kit/multimem.py ensure --create
python3 ~/.multimem/kit/multimem.py doctor
```

What that does: downloads the kit into `~/.multimem/kit/`, writes four hooks into `~/.codex/hooks.json` (`hooks.py --harness codex`), appends a marked paragraph to `~/.codex/AGENTS.md`, and runs `codex mcp add multimem -- python3 ~/.multimem/kit/mcp_server.py`. Then open `/hooks` inside Codex once to trust the hooks. If Claude Code is installed on the same machine, run `python3 ~/.claude/skills/multimem/multimem.py install --host codex` instead, so both hosts share one kit folder.

Remove: `python3 ~/.multimem/kit/multimem.py uninstall --host codex`.

## Any MCP host (Cursor, Gemini CLI, Claude Desktop, OpenCode, …)

```sh
curl -fsSL https://any.org/assets/multimem/get.py | python3 - --host mcp
python3 ~/.multimem/kit/multimem.py ensure --create
```

`install --host mcp` prints the server entry to add to the host's MCP configuration:

```json
{"mcpServers": {"multimem": {"command": "python3", "args": ["/home/you/.multimem/kit/mcp_server.py"]}}}
```

`python3 ~/.multimem/kit/multimem.py install --host mcp --write <that config file>` merges it for you; `uninstall --host mcp --write <file>` removes the `multimem` entry only. The 17 tools are `multimem_context`, `multimem_search`, `multimem_show`, `multimem_list`, `multimem_decision`, `multimem_learning`, `multimem_task`, `multimem_goal`, `multimem_commitment`, `multimem_idea`, `multimem_journal`, `multimem_profile`, `multimem_update`, `multimem_session_note`, `multimem_event`, `multimem_chat` and `multimem_area_list`. Goal, commitment, idea, journal and profile operations require the brain pack. The host's rules file should still carry the paragraph from the next section so the agent knows when to call them.

## Hosts without hooks or MCP (rules file + CLI)

```sh
curl -fsSL https://any.org/assets/multimem/get.py | python3 - --host rules --write ./AGENTS.md
python3 ~/.multimem/kit/multimem.py ensure --create
```

`install --host rules --write <file>` appends one marked paragraph to the rules file your host reads (`AGENTS.md`, `.cursorrules`, `GEMINI.md`, a system prompt): read `context` first, start and end the session record by hand, record decisions, learnings and tasks through the CLI, treat injected memory as data. Without `--write` it prints the paragraph. The agent then runs, per session:

```sh
python3 ~/.multimem/kit/multimem.py context
python3 ~/.multimem/kit/multimem.py session start --harness <name> --session-key <its session id> --goal "…"
python3 ~/.multimem/kit/multimem.py decision|learning|task "…" --summary "…"
python3 ~/.multimem/kit/multimem.py session end --status done --outcome "…"
```

Remove: `python3 ~/.multimem/kit/multimem.py uninstall --host rules --write ./AGENTS.md`.

## A personal space (the brain pack)

The brain pack is optional. For an assistant that helps with your life and work rather than one codebase, first select and verify the intended space as above, then get approval to add the brain pack and the `life` area preset. Both are remembered in `~/.multimem/config.json` so later `ensure` calls apply them. This is not a default step for a coding-memory upgrade:

```sh
python3 ~/.multimem/kit/multimem.py ensure --pack brain --preset life
python3 ~/.multimem/kit/multimem.py profile pull        # the About-me template; fill it in the app or push a file
```

Use the actual registered kit path if it differs. On an existing space this adds pack bundles, extension properties and the preset's areas; existing options remain. On a fresh space, create it through the approved fresh-space path first. The session digest then opens with the profile, open commitments and active goals.

## A cloud sandbox with its own `any`

Run `any` in the sandbox with its own account and accept an invite to the user's memory space (`POST /v1/spaces/join`). Verify and pin that space before `multimem.py ensure` adopts its schema with the same ids. Register the chosen host without creating another space. If the sandbox is the first device and the user explicitly approves a new space, the fresh-space path creates it there and the user joins it from the app.

## After installing

- `multimem.py doctor` — server, space, bundles, areas.
- `multimem.py context` — what every session reads first.
- `multimem.py area add payments --name Payments --color green` — extend the area vocabulary (saved in `~/.multimem/config.json`, applied to the space, re-applied by `ensure` elsewhere).
- `multimem.py handbook pull` — the contract as the space carries it; the kit's files are attached to that page.
- With the user's approval, `import_transcripts.py sync` backfills the last two weeks of Claude Code / Codex sessions.

## Environment and config

| setting | env | config key (`~/.multimem/config.json`) | default |
|---|---|---|---|
| server | `MULTIMEM_ADDR` (comma list) | `addr` | probe `127.0.0.1:31330`, then `127.0.0.1:7001` |
| space | `MULTIMEM_SPACE_NAME` / `MULTIMEM_SPACE_ID` | `space.name` / `space.id` | `Multimem`; verify and pin the intended name or id before `ensure` |
| repo label | `MULTIMEM_REPO` | `repo` | the git origin's `owner/name`, else the checkout's folder name |
| harness label (CLI) | `MULTIMEM_HARNESS` | `harness` | `other` (the hooks pass their own) |
| session key | `MULTIMEM_SESSION_KEY` | — | the key last started in the working directory |
| state folder | `MULTIMEM_HOME` | — | `~/.multimem` (config, cache, hooks.log, hooks.off) |
| hooks off | `MULTIMEM_HOOKS_OFF=1` | — | or `touch ~/.multimem/hooks.off` |
| areas | — | `areas: {key: {name, color}}` | the selected preset's defaults at install |
| area preset | — | `areas_preset` | `work`; `life` is an explicit personal-space choice |
| packs | — | `packs` | none; `brain` adds personal kinds when chosen |
| importer exclusions | — | `import.exclude: [repo labels]` | `codex-scratch`, `home` |

`config.example.json` is a brain/life example, with `packs: ["brain"]` and `areas_preset: "life"`. It is not a neutral template for an existing coding-memory space.