[Musyg]

Step 4 of the plan: one package, and one command to connect each tool. Stacked on #15.

What changes

• The distribution is renamed persistent-memory, version 0.4.0a1. The import name stays hermes_memory. Releases up to 0.3.0a5 keep their old name; the docs say to uninstall hermes-memory-core first, since both contain the same module.
• New persistent-memory command:
  • setup <client> for claude-code, claude-desktop, cursor, vscode (GitHub Copilot), windsurf, codex and hermes-agent, with --scope user|project, --store, --workspace, --name, --dry-run, --remove, --force;
  • status: default store and which client files already run this memory;
  • mcp: the MCP server itself.
• Every client gets the same store, in the platform data folder by default ($XDG_DATA_HOME or ~/.local/share, ~/Library/Application Support, %LOCALAPPDATA%), and the same workspace. setup creates the store once; the configured server does not recreate a missing one.
• persistent-memory-mcp uses that same default when neither --store nor PERSISTENT_MEMORY_DIR is given.
• Hermes Agent: from Hermes Agent's own environment, setup selects the memory provider (hermes config set memory.provider) and writes the store into the provider settings; otherwise it adds the MCP server through hermes config set mcp_servers.*.

Extras

Decision A planned extras per door. Since step 3 every door uses the standard library only, so they would be empty: this is one package with no extras and no dependency.

Safety rules of setup

• Other entries and settings are kept.
• An unparsable file (JSON with comments, invalid TOML) is never touched; the entry to add by hand is printed.
• An entry of the same name that runs another server needs --force.
• Existing files are copied to <file>.persistent-memory-<time>.bak, then replaced atomically; symlinks are followed; file mode is kept.
• A second run changes nothing.
• Codex TOML is parsed again before writing; if anything besides the entry would change, nothing is written.
• Claude Code (user scope) and Hermes Agent are changed through their own CLIs, never by editing their files.

Verification

• tests/test_client_setup.py: 26 methods (324 public in total). 14 mutations of the setup module, all detected.
• Installed qualification (scripts/check_distributions.py, wheel and rebuilt sdist): memory 324 and registry 49, no failure, error or skip, on Python 3.11 and 3.12 in Docker (Linux), and on Python 3.13 in a separate Linux environment.
• Fresh virtual environment, Python 3.12, package installed from its wheel, each tool on a temporary configuration folder:
  • Claude Code 2.1.289: setup claude-code registered the server, a second run reported it unchanged, claude mcp list showed it connected.
  • Codex CLI 0.166.0: codex mcp list and codex mcp get read the entry written by setup codex.
  • Hermes Agent: hermes memory status showed persistent-memory active and available. With a local 9B model, Hermes Agent stored a fact with memory_remember; the server configured for Claude Code and Codex found it with memory_search.
• Claude Desktop, Cursor, VS Code and Windsurf files follow each tool's current documentation and are covered by tests, but were not opened in those applications. macOS and Windows paths are implemented and tested on Linux only; step 5 runs them on those systems.

Core bytes unchanged (80c55792...). PROVENANCE.json updated.