# Enabling memprove in a project

The second step, once per repository, from inside its Git worktree:

```bash
memprove init                              # the detected clients
memprove init --allow-tools                # and Claude Code's allow rules
memprove init --client claude-code --client codex --client cursor --dry-run
```

`init` registers the Project with the operator's token (a repository already registered gets its Project back) and
records it for the first `memprove begin` there (which then needs no `--project`), adds `.claude/settings.local.json`
and `.mcp.json` (and Cursor's `.cursor/mcp.json` and `.cursor/rules/memprove.mdc`) to `.git/info/exclude`, runs `hook
install` for Claude Code (with `--allow-tools`, `hook install --allow-tools`; without it the three rules are printed,
not written), writes `[mcp_servers.memprove]` into Codex's `config.toml` (`$CODEX_HOME`, else `~/.codex`) and a short
note into `AGENTS.md` (repository content: commit it), writes `mcpServers.memprove` into `.cursor/mcp.json` and the
same note as an always-applied Cursor rule, and ends with `doctor`. Every file keeps its other content; run again, it
changes nothing (`already as asked`). What `init` wrote under the previous name `continuity` is replaced (the
`AGENTS.md` note, the Codex table, the Claude Code entries), and an unedited `.cursor/rules/continuity.mdc` is
removed. Neither token is printed. Before the first `begin`, `doctor` warns and exits 0: its `workspace` line says the
Workspace has no context yet, and its `ledger` line says `not checked: no context names a Project here` (`ledger`
(`not checked: no context names a Project here`)); both pass after the first Session. `--allow-tools` writes the rules
for the MCP server and for `memprove run` only. Whether the agent may `Edit` files or run `git add` and `git commit`
is the operator's decision for each project, and nothing here allows it: a `claude -p` run with no rule for them is
refused those tools as `permission_denied`, edits nothing, and cannot commit before the run that is its Evidence. Add
the rules the Task needs by hand; "Unattended takeover" ("What to allow") lists them and says why.

What `init` writes by hand, when you prefer that: `memprove mcp print-config` prints the two parts, each under a
line `==> <file> <==`: the `.claude/settings.local.json` part (`hooks.SessionStart`, `env.MEMPROVE_CONFIG_DIR`, the
suggested `permissions.allow`) and the `.mcp.json` part (`mcpServers.memprove`). The entry runs this `memprove` by
its absolute path with the arguments `hook session-start` (exec form, no shell, timeout 10 seconds, every source),
followed by `--config-dir <config>`, which wins over a `MEMPROVE_CONFIG_DIR` the process inherits. `memprove hook
install` writes the hook and the `env` into the settings file and the server into `.mcp.json`, keeps every other
member of either file, and rewrites an entry an earlier install wrote without `--config-dir`; `--allow-tools` adds the
three rules it names. Running `install` again changes nothing. In a repository enabled under the previous name
`continuity`, it replaces that installation's handler, `env.CONTINUITY_CONFIG_DIR` and `mcpServers.continuity` (and,
with `--allow-tools`, its three rules) instead of adding its own beside them. Claude Code reads MCP servers from `<Workspace
root>/.mcp.json` (project scope) or `~/.claude.json` (local or user scope), never from a settings file. Run the
`claude mcp add` line that `mcp print-config` gives on standard error (`claude mcp add --transport stdio --scope
project --env MEMPROVE_CONFIG_DIR=<config> memprove -- <path> mcp serve --config-dir <config>`) instead of `hook
install` if you prefer. `memprove hook uninstall` removes the hook, the `env` and the server entry again (those of the
previous name too) and leaves `permissions.allow`.

### The agent's environment

The commands an agent runs in its shell take the data directory from `--data-dir` (or `--socket`), else
`MEMPROVE_DATA_DIR`, else the one line of `<config>/data-dir`, and the token from `--token-file`, else
`MEMPROVE_TOKEN`, else the file `MEMPROVE_TOKEN_FILE` names, else `<config>/token`. The SessionStart hook and the
MCP server read the same variables first and fall back to those two files. The configuration directory is
`--config-dir` (hook and server), else `MEMPROVE_CONFIG_DIR`, else `~/.memprove/config` when it exists (the
default installation), else `$XDG_CONFIG_HOME/memprove`, else `~/.config/memprove`. An empty variable counts as
unset. `begin` refuses a configuration directory inside the Workspace: its context files are one 0600 file per
Workspace root, never inside the Workspace. A token's text never goes into a file of the repository, `.mcp.json` or
`.claude/settings.local.json`.

For another prefix, set these where the client is started (the shell profile is what `install.sh --write-profile`
writes):

```bash
export PATH="/opt/memprove/bin:$PATH"
export MEMPROVE_CONFIG_DIR=/opt/memprove/config
export MEMPROVE_DATA_DIR=/opt/memprove/data
export MEMPROVE_TOKEN_FILE=/opt/memprove/config/token
```

The agent's own name and role are variables of the same environment: `MEMPROVE_AGENT_NAME`, `MEMPROVE_AGENT_ROLE`
(`orchestrator`, `sub_agent` or `human`) and, for a dispatched agent, `MEMPROVE_PARENT_SESSION`. `memprove begin`
in the shell and the MCP server's `begin` and `end` read them when given no agent option or input, and the
SessionStart hook reads them too: with both set, the opening before the Pack has `You are agent「<name>」(<role>[,
parent Session <ID>]); when begin and end get no agent_name, agent_role, or parent_session, the server uses these
three.`, so the client learns its name from the injected text without reading its environment (under the evaluation's
allow rules a command that expands a variable or calls `printenv`, `env`, or `date` is refused, none of them being a
memprove command, and the opening's name, time, and parent need no such read). With only part of the declaration
set, or a value the server refuses, the opening names no agent and the hook writes one line on standard error; `begin`
and `end` refuse that declaration too (`invalid_arguments`). The opening always has `The current UTC time is <time>.`,
the hook's clock in the form of the Pack's `last wrote to the ledger at <time>`, and ends with the open-item sentence
of "Which open Session to end" below. None of these sentences is part of the Pack: its bytes and its digest are those
of `resume --pack`.

Run `memprove run` as a command of its own: not joined with `echo`, `git status`, or a command that writes a file,
by `&&`, `;`, a pipe, or a heredoc. The permission rule `Bash(memprove run:*)` matches a command by its prefix, and
a client that has no one to ask refuses a compound command when a part of it is not allowed.

### Keep memprove's files out of Evidence

`init` adds the client files to `.git/info/exclude`. Left untracked, either file changes the repository state the
probe sees: the facts recorded before it read `stale` (`worktree_changed`), no run is carried, a fact on a later run
is `unconfirmed` (`evidence_unavailable`, with the gap `untracked_files_not_captured`), and `task complete` answers
`409 evidence_stale`. `git rev-parse --git-path info/exclude` names the repository's own exclude file, never
committed, which holds for every linked worktree. Leave `.mcp.json` out of the list when the project commits it.
The same holds for what a test run leaves behind, such as Python's `__pycache__/`: while `git status --short` lists an
untracked file, every fact on a run is `unconfirmed`, so list such files in `.gitignore` or in the exclude file.
`AGENTS.md` and `.cursor/rules/memprove.mdc` are not excluded: the note is repository content and is committed.