Enabling memprove in a project

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

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):

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.

From docs/guide.md at 2625064cbf0a · Markdown