Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat: add lifecycle uninstall helper and update/remove docs (v0.4.1)

Sol Aitken5fb86c95b560
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index c4129654..467d20cf 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.4.0",
+ "version": "0.4.1",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": "Open Second Brain contributors",
"license": "MIT",
@@ -50,6 +50,12 @@
"command": "scripts/o2b",
"args": ["mcp"]
},
+ {
+ "name": "uninstall",
+ "description": "Print an uninstall plan; --apply-local removes only the machine-local config directory.",
+ "command": "scripts/o2b",
+ "args": ["uninstall"]
+ },
{
"name": "vault-log",
"description": "Compatibility wrapper for appending event log entries.",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 874d62ea..c7586d56 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.4.0",
+ "version": "0.4.1",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, and other agent runtimes.",
"skills": "./skills",
"keywords": ["second-brain", "obsidian", "agents", "skills", "event-log", "mcp"]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3f08d74e..533a234d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [0.4.1] - 2026-05-06
+
+### Added
+
+- `o2b uninstall` CLI helper that prints a read-only uninstall plan, including
+ the exact Hermes commands the user must run (`hermes mcp remove`,
+ `hermes plugins remove`, `hermes gateway restart`) and the location of the
+ machine-local config directory.
+- `--apply-local` flag for `o2b uninstall` that may remove the machine-local
+ config directory only (`~/.config/open-second-brain` or the parent of
+ `$OPEN_SECOND_BRAIN_CONFIG`). Refuses to act on directories whose name is
+ not a recognized Open Second Brain config dir, paths inside Hermes-owned
+ trees, or directories that look like git repositories.
+- `after-install.md` at the repository root so Hermes can show post-install
+ guidance (init, MCP registration, update, uninstall) right after
+ `hermes plugins install`.
+- `uninstall` command entry in the Claude Code plugin manifest.
+- README now documents an explicit Hermes CLI form for MCP registration
+ (`hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault`)
+ and adds dedicated **Updating** and **Uninstalling** sections that spell
+ out the Hermes-owned vs. machine-local layers.
+- `docs/mcp.md` now covers updating and removing the MCP registration, and
+ warns against passing `--args` as a single quoted string.
+- Dedicated `tests/test_uninstall.py` covering dry-run safety, vault and
+ Hermes config preservation, the `--apply-local` allow-list, the
+ `OPEN_SECOND_BRAIN_CONFIG` env override, and the help text invariants.
+
+### Changed
+
+- Bumped package, plugin, and Claude/Codex manifest versions to 0.4.1.
+
+### Migration / Uninstall notes
+
+- `o2b uninstall` is read-only by default. It **never** edits
+ `~/.hermes/config.yaml`, removes the installed plugin directory, or
+ touches the vault β€” including `Daily/`, `AI Wiki/`, or any Markdown.
+- To deregister the MCP server and remove the plugin run the Hermes
+ commands yourself (`hermes mcp remove open-second-brain`,
+ `hermes plugins remove open-second-brain`, `hermes gateway restart`).
+- `o2b uninstall --apply-local` only removes the machine-local
+ Open Second Brain config directory; it refuses to delete anything else.
+- Existing users do not need to re-register the MCP server after upgrading
+ to 0.4.1; the plugin update flow keeps `~/.hermes/config.yaml` untouched.
+
## [0.4.0] - 2026-05-06
### Added
@@ -48,7 +92,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
-[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.4.0...HEAD
+[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/itechmeat/open-second-brain/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/itechmeat/open-second-brain/compare/v0.3.1...v0.4.0
[0.3.1]: https://github.com/itechmeat/open-second-brain/compare/v0.3.0...v0.3.1
[0.3.0]: https://github.com/itechmeat/open-second-brain/releases/tag/v0.3.0
diff --git a/README.md b/README.md
index defadb37..faa4b250 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,7 @@ o2b append-event Append one daily event-log entry
o2b index Rebuild the Markdown page index
o2b export-config Write a redacted config snapshot
o2b mcp Run the optional MCP tool server (stdio)
+o2b uninstall Print an uninstall plan; --apply-local removes only local config
vault-log Compatibility wrapper around append-event
```
@@ -83,7 +84,13 @@ The local checkout can be used without installing the Python package. Run comman
## Optional MCP tool server
-OpenSecondBrain ships an optional Model Context Protocol server that exposes the same deterministic operations as MCP tools. Hermes Agent discovers it through `~/.hermes/config.yaml`:
+OpenSecondBrain ships an optional Model Context Protocol server that exposes the same deterministic operations as MCP tools. Register it through Hermes from the CLI:
+
+```bash
+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
+```
+
+Or edit `~/.hermes/config.yaml` directly:
```yaml
mcp_servers:
@@ -94,6 +101,56 @@ mcp_servers:
Tools: `second_brain_status`, `second_brain_query`, `second_brain_capture`, `event_log_append`, `vault_health`. See `docs/mcp.md` for full setup, tool schemas, and Claude Code/Codex notes. The CLI remains the supported baseline; the MCP server is opt-in.
+## Updating
+
+OpenSecondBrain follows the standard Hermes plugin update flow.
+
+```bash
+hermes plugins update open-second-brain
+hermes gateway restart
+```
+
+`hermes plugins update` runs `git pull` inside the installed plugin directory; it does not rewrite your `~/.hermes/config.yaml` MCP registration. After an update:
+
+- The `o2b` CLI is upgraded automatically.
+- The MCP entrypoint stays registered, so no `hermes mcp add` is needed for an in-place upgrade.
+- Restart the gateway (or open a fresh Hermes session) so cached plugin metadata and the MCP subprocess are reloaded.
+- Run `o2b doctor --vault /path/to/vault --repo .` to confirm the new manifest still validates.
+
+The `version` field in `plugin.yaml` is informational β€” Hermes installs whatever the current `main` branch contains. Pin to a specific release by checking out a tag inside the plugin directory if you want stricter control.
+
+## Uninstalling
+
+OpenSecondBrain treats your vault as the source of truth and never removes Markdown notes, `Daily/`, or `AI Wiki/`. Uninstalling has three independent layers; do them in this order.
+
+1. Print a plan and review the leftovers (read-only):
+
+ ```bash
+ o2b uninstall
+ ```
+
+ The plan tells you which Hermes commands to run yourself, where the machine-local config directory lives, and reminds you that the vault is untouched. The dry-run never modifies the filesystem.
+
+2. Deregister the MCP server and remove the Hermes plugin (Hermes-owned state):
+
+ ```bash
+ hermes mcp remove open-second-brain
+ hermes plugins remove open-second-brain
+ hermes gateway restart
+ ```
+
+ `hermes mcp remove` deletes the MCP registration and any OAuth tokens. `hermes plugins remove` deletes only the installed plugin directory. OpenSecondBrain itself never edits `~/.hermes/config.yaml` β€” these commands are run by you against Hermes.
+
+3. Optionally remove the machine-local config directory (typically `~/.config/open-second-brain` or `$OPEN_SECOND_BRAIN_CONFIG`'s parent):
+
+ ```bash
+ o2b uninstall --apply-local
+ ```
+
+ `--apply-local` only removes that one config directory. It refuses to act if the directory name is not a recognized Open Second Brain config dir, if it lives inside a Hermes-owned path, or if it looks like a git repository. It never touches the vault, Hermes config, or anything else.
+
+To delete the vault you must do that yourself with normal filesystem tools β€” OpenSecondBrain will not do it for you, even with `--apply-local`.
+
## Safety model
- Your notes stay as plain Markdown.
diff --git a/after-install.md b/after-install.md
new file mode 100644
index 00000000..ac49d471
--- /dev/null
+++ b/after-install.md
@@ -0,0 +1,79 @@
+# Open Second Brain β€” after install
+
+Thanks for installing Open Second Brain. The plugin is now on disk; finish
+the setup with the steps below.
+
+## 1. Initialise a vault
+
+Pick (or create) the Obsidian-compatible folder you want as your second
+brain, then bootstrap the agent-owned files:
+
+```bash
+o2b init --vault /path/to/vault --name "My Second Brain"
+o2b doctor --vault /path/to/vault --repo .
+```
+
+`o2b doctor` should print `[OK]` for every check.
+
+## 2. Register the MCP server (optional but recommended)
+
+Open Second Brain ships an optional stdio MCP server. Register it with
+Hermes so the deterministic tools are routable:
+
+```bash
+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
+hermes gateway restart
+```
+
+`--args` is a single flag whose value is the remaining tokens on the line
+(here: `mcp --vault /path/to/vault`). Hermes hands those tokens to the MCP
+server's command line as-is β€” do not wrap them in one quoted string like
+`--args 'mcp --vault /path/to/vault'`, and do not repeat `--args` per token.
+Edit `~/.hermes/config.yaml` instead if you prefer YAML.
+
+The CLI works on its own; the MCP server is opt-in. See `docs/mcp.md` for
+tool schemas, per-tool arguments, and Claude Code / Codex notes.
+
+## 3. Updating
+
+```bash
+hermes plugins update open-second-brain
+hermes gateway restart
+```
+
+`hermes plugins update` runs `git pull` inside the plugin directory. Your
+MCP registration in `~/.hermes/config.yaml` is preserved across updates.
+
+## 4. Uninstalling
+
+Run a dry-run first to see exactly what will happen and which Hermes
+commands you need to run:
+
+```bash
+o2b uninstall
+```
+
+Then deregister the MCP server and remove the plugin (Hermes-owned state):
+
+```bash
+hermes mcp remove open-second-brain
+hermes plugins remove open-second-brain
+hermes gateway restart
+```
+
+Optional: remove the machine-local config directory only:
+
+```bash
+o2b uninstall --apply-local
+```
+
+`--apply-local` only touches `~/.config/open-second-brain` (or the parent
+of `$OPEN_SECOND_BRAIN_CONFIG`). Your vault, `Daily/`, `AI Wiki/`, and
+Markdown notes are never removed by Open Second Brain β€” delete them
+yourself with normal filesystem tools if that is what you want.
+
+## More
+
+- `README.md` β€” full feature description and CLI reference.
+- `docs/mcp.md` β€” MCP tool server, registration, update/remove flows.
+- `docs/architecture.md` β€” config model, vault layout, security rules.
diff --git a/docs/mcp.md b/docs/mcp.md
index 9ac92686..cfc7b920 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -53,7 +53,21 @@ The server logs its banner to `stderr` and only writes JSON-RPC frames to
Hermes discovers MCP servers from `~/.hermes/config.yaml` under the
`mcp_servers` key. After installing this plugin, register the MCP server on
-the same machine that hosts the vault:
+the same machine that hosts the vault.
+
+The Hermes CLI accepts the registration directly:
+
+```bash
+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
+```
+
+`--args` is a single flag; everything after it on the line (here
+`mcp --vault /path/to/vault`) is collected as the argument list and forwarded
+to the MCP server's command line. Do not wrap those tokens in a single
+quoted string like `--args 'mcp --vault /path'` (Hermes would treat the whole
+thing as one argument), and do not repeat `--args` per token.
+
+You can also edit `~/.hermes/config.yaml` by hand:
```yaml
mcp_servers:
@@ -88,6 +102,53 @@ The Hermes plugin manifest (`plugin.yaml`) advertises this MCP entrypoint via
the `mcp_server` field so future Hermes releases can auto-register the server,
but the official Hermes config flow is the source of truth today.
+## Updating the MCP registration
+
+Updating the plugin via `hermes plugins update open-second-brain` does not
+rewrite `~/.hermes/config.yaml`. Your existing `mcp_servers.open-second-brain`
+entry keeps working as long as the `command` and `args` you originally
+registered still resolve.
+
+After an update:
+
+- Restart the gateway so the MCP subprocess is reloaded:
+
+ ```bash
+ hermes gateway restart
+ ```
+
+- If the new release adds a flag, re-add the registration with the updated
+ `--args` list (or edit the YAML by hand):
+
+ ```bash
+ hermes mcp remove open-second-brain
+ hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
+ ```
+
+`scripts/o2b mcp --vault /path/to/vault` from the checkout can be used to
+sanity-check the server before re-registering it.
+
+## Removing the MCP registration
+
+To remove just the MCP server without uninstalling the plugin, run:
+
+```bash
+hermes mcp remove open-second-brain
+hermes gateway restart
+```
+
+`hermes mcp remove` deletes the registration entry. Open Second Brain runs
+over stdio (JSON-RPC 2.0) and does not use OAuth, so there are no tokens for
+this server specifically; the OAuth-token cleanup `hermes mcp remove` performs
+only matters for transports that authenticate that way. The installed plugin
+and its CLI commands stay in place, so `hermes plugins update` will continue
+to track new releases.
+
+To remove both the MCP server and the plugin itself, follow the
+`Uninstalling` section in the project README. Open Second Brain never edits
+`~/.hermes/config.yaml` on your behalf, and `o2b uninstall` is a read-only
+helper that prints the exact Hermes commands to run.
+
## Claude Code and Codex
The Claude Code plugin manifest exposes `o2b mcp` as a regular command that
diff --git a/plugin.yaml b/plugin.yaml
index a53e7c85..3d090152 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.4.0"
+version: "0.4.1"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 5876479c..96e2afa2 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.4.0"
+version: "0.4.1"
description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index 500b12cb..0081bcef 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "open-second-brain"
-version = "0.4.0"
+version = "0.4.1"
description = "Hermes-first second brain package for Obsidian-compatible Markdown vaults."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/open_second_brain/__init__.py b/src/open_second_brain/__init__.py
index 2c472b92..1023395c 100644
--- a/src/open_second_brain/__init__.py
+++ b/src/open_second_brain/__init__.py
@@ -1,3 +1,3 @@
"""Open Second Brain core package."""
-__version__ = "0.4.0"
+__version__ = "0.4.1"
diff --git a/src/open_second_brain/cli.py b/src/open_second_brain/cli.py
index 4fb8141f..ed6f8b47 100644
--- a/src/open_second_brain/cli.py
+++ b/src/open_second_brain/cli.py
@@ -11,6 +11,7 @@ from open_second_brain.doctor import doctor
from open_second_brain.event_log import append_event
from open_second_brain.init import bootstrap_vault
from open_second_brain.mcp import run_cli_command as run_mcp_server
+from open_second_brain.uninstall import plan_uninstall, render_plan
from open_second_brain.vault import list_vault_pages, write_frontmatter
@@ -57,6 +58,28 @@ def build_parser() -> argparse.ArgumentParser:
mcp_cmd.add_argument("--config", type=Path, default=None, help="Config file path")
mcp_cmd.add_argument("--repo", type=Path, default=None, help="Repository root for plugin checks")
+ uninstall_cmd = subcommands.add_parser(
+ "uninstall",
+ help="Print an uninstall plan and (optionally) clean local config",
+ description=(
+ "Read-only by default. Prints the Hermes commands you must run yourself "
+ "(this tool never touches ~/.hermes/config.yaml or the installed plugin). "
+ "With --apply-local it may remove the machine-local Open Second Brain "
+ "config directory only. Your vault, Daily/, AI Wiki/, and Markdown notes "
+ "are never removed."
+ ),
+ )
+ uninstall_cmd.add_argument("--config", type=Path, default=None, help="Config file path")
+ uninstall_cmd.add_argument(
+ "--apply-local",
+ action="store_true",
+ help=(
+ "Remove the machine-local Open Second Brain config directory "
+ "(typically ~/.config/open-second-brain). Hermes config and the vault "
+ "are never touched."
+ ),
+ )
+
return parser
@@ -179,6 +202,15 @@ def command_mcp(args: argparse.Namespace) -> int:
return 0
+def command_uninstall(args: argparse.Namespace) -> int:
+ config = args.config or default_config_path()
+ plan = plan_uninstall(config_path=config, apply_local=args.apply_local)
+ sys.stdout.write(render_plan(plan))
+ if plan.errors:
+ return 1
+ return 0
+
+
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
@@ -196,6 +228,8 @@ def main(argv: list[str] | None = None) -> int:
return command_index(args)
if args.command == "mcp":
return command_mcp(args)
+ if args.command == "uninstall":
+ return command_uninstall(args)
raise AssertionError(f"unhandled command: {args.command}")
diff --git a/src/open_second_brain/mcp.py b/src/open_second_brain/mcp.py
index ca94fe09..173b6422 100644
--- a/src/open_second_brain/mcp.py
+++ b/src/open_second_brain/mcp.py
@@ -29,7 +29,7 @@ from open_second_brain.vault import list_vault_pages, parse_frontmatter, write_f
PROTOCOL_VERSION = "2025-06-18"
SERVER_NAME = "open-second-brain"
-SERVER_VERSION = "0.4.0"
+SERVER_VERSION = "0.4.1"
JSONRPC_VERSION = "2.0"
# JSON-RPC 2.0 error codes used by the MCP server.
diff --git a/src/open_second_brain/uninstall.py b/src/open_second_brain/uninstall.py
new file mode 100644
index 00000000..3a85e99a
--- /dev/null
+++ b/src/open_second_brain/uninstall.py
@@ -0,0 +1,211 @@
+"""Read-only uninstall planner for Open Second Brain.
+
+The uninstall helper does NOT manage the Hermes plugin install or
+MCP registration; those are owned by Hermes. It also never touches the
+user's vault. By default it is a dry-run that prints the plan and the
+exact Hermes commands the user should run themselves.
+
+When invoked with ``--apply-local`` it may delete the machine-local
+Open Second Brain config directory (typically ``~/.config/open-second-brain``).
+Anything outside that single directory is left untouched.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+from open_second_brain.config import discover_config
+
+PLUGIN_NAME = "open-second-brain"
+
+HERMES_COMMANDS: tuple[str, ...] = (
+ f"hermes mcp remove {PLUGIN_NAME}",
+ f"hermes plugins remove {PLUGIN_NAME}",
+ "hermes gateway restart",
+)
+
+SAFE_CONFIG_DIR_NAMES: frozenset[str] = frozenset({"open-second-brain", "open_second_brain"})
+
+
+@dataclass(frozen=True)
+class UninstallPlan:
+ """Computed plan for an uninstall invocation."""
+
+ config_path: Path
+ config_exists: bool
+ config_dir: Path
+ config_dir_exists: bool
+ config_dir_entries: tuple[Path, ...]
+ vault_path: Path | None
+ apply_local: bool
+ hermes_commands: tuple[str, ...] = HERMES_COMMANDS
+ removed_paths: tuple[Path, ...] = field(default_factory=tuple)
+ skipped_paths: tuple[tuple[Path, str], ...] = field(default_factory=tuple)
+ errors: tuple[tuple[Path, str], ...] = field(default_factory=tuple)
+
+
+def _is_safe_local_config_dir(target: Path) -> tuple[bool, str]:
+ """Return ``(safe, reason)`` for ``target`` as a deletion candidate.
+
+ Only a directory whose final name is one of the well-known Open Second
+ Brain config dir names is eligible. The directory must also live outside
+ any Hermes config tree to keep us strictly off Hermes-owned state.
+ """
+
+ if target.name not in SAFE_CONFIG_DIR_NAMES:
+ return False, (
+ f"directory name '{target.name}' is not a recognized Open Second Brain "
+ "config directory; refusing to remove"
+ )
+
+ parts_lower = {part.lower() for part in target.parts}
+ if ".hermes" in parts_lower or "hermes" in parts_lower:
+ return False, "config directory is inside a Hermes-owned path; refusing to remove"
+
+ if (target / ".git").exists():
+ return False, "config directory looks like a git repository; refusing to remove"
+
+ return True, ""
+
+
+def _vault_path_from_config(data: dict[str, str]) -> Path | None:
+ for key in ("vault_path", "vault", "vault_dir", "path"):
+ value = data.get(key)
+ if value:
+ return Path(value).expanduser()
+ return None
+
+
+def _list_entries(directory: Path) -> tuple[Path, ...]:
+ if not directory.is_dir():
+ return ()
+ try:
+ return tuple(sorted(directory.iterdir()))
+ except OSError:
+ return ()
+
+
+def plan_uninstall(
+ *,
+ config_path: Path,
+ apply_local: bool = False,
+) -> UninstallPlan:
+ """Compute (and optionally apply-local) an uninstall plan.
+
+ The plan never modifies the Hermes config, the installed plugin
+ directory, or the user's vault. With ``apply_local=True`` it may
+ remove the machine-local config directory if and only if it passes
+ :func:`_is_safe_local_config_dir`.
+ """
+
+ discovery = discover_config(config_path)
+ cfg_dir = discovery.path.parent
+ cfg_dir_exists = cfg_dir.is_dir()
+ entries = _list_entries(cfg_dir)
+ vault_path = _vault_path_from_config(discovery.data)
+
+ removed: list[Path] = []
+ skipped: list[tuple[Path, str]] = []
+ errors: list[tuple[Path, str]] = []
+
+ if apply_local:
+ if not cfg_dir_exists:
+ skipped.append((cfg_dir, "config directory does not exist"))
+ else:
+ safe, reason = _is_safe_local_config_dir(cfg_dir)
+ if not safe:
+ skipped.append((cfg_dir, reason))
+ else:
+ try:
+ shutil.rmtree(cfg_dir)
+ removed.append(cfg_dir)
+ except OSError as exc:
+ errors.append((cfg_dir, str(exc)))
+
+ return UninstallPlan(
+ config_path=discovery.path,
+ config_exists=discovery.exists,
+ config_dir=cfg_dir,
+ config_dir_exists=cfg_dir_exists,
+ config_dir_entries=entries,
+ vault_path=vault_path,
+ apply_local=apply_local,
+ removed_paths=tuple(removed),
+ skipped_paths=tuple(skipped),
+ errors=tuple(errors),
+ )
+
+
+def render_plan(plan: UninstallPlan) -> str:
+ """Render an :class:`UninstallPlan` as plain text for the CLI."""
+
+ lines: list[str] = []
+ title = "Open Second Brain β€” Uninstall plan"
+ lines.append(title)
+ lines.append("=" * len(title))
+ lines.append("")
+
+ mode = "apply-local (machine-local config directory may be removed)" if plan.apply_local else "dry-run (read-only)"
+ lines.append(f"Mode: {mode}")
+ lines.append("")
+
+ lines.append("Local config:")
+ config_state = "exists" if plan.config_exists else "missing"
+ lines.append(f" config file: {plan.config_path} ({config_state})")
+ if plan.config_dir_exists:
+ entry_count = len(plan.config_dir_entries)
+ lines.append(f" config dir: {plan.config_dir} ({entry_count} entr{'y' if entry_count == 1 else 'ies'})")
+ for entry in plan.config_dir_entries:
+ suffix = "/" if entry.is_dir() else ""
+ lines.append(f" - {entry.name}{suffix}")
+ else:
+ lines.append(f" config dir: {plan.config_dir} (missing)")
+ lines.append("")
+
+ lines.append("Hermes integration (run these yourself; this tool will not):")
+ for cmd in plan.hermes_commands:
+ lines.append(f" $ {cmd}")
+ lines.append("")
+ lines.append(" Hermes owns plugin installation and MCP registration. Open Second")
+ lines.append(" Brain never edits ~/.hermes/config.yaml on your behalf.")
+ lines.append("")
+
+ lines.append("Vault (NEVER removed by this tool):")
+ if plan.vault_path is not None:
+ lines.append(f" {plan.vault_path}")
+ else:
+ lines.append(" (no vault path recorded in config; check your runtime settings)")
+ lines.append(" Your Markdown notes, Daily/, and AI Wiki/ stay exactly as they are.")
+ lines.append("")
+
+ if plan.apply_local:
+ lines.append("Apply-local results:")
+ if plan.removed_paths:
+ for path in plan.removed_paths:
+ lines.append(f" removed: {path}")
+ if plan.skipped_paths:
+ for path, reason in plan.skipped_paths:
+ lines.append(f" skipped: {path} β€” {reason}")
+ if plan.errors:
+ for path, reason in plan.errors:
+ lines.append(f" error: {path} β€” {reason}")
+ if not (plan.removed_paths or plan.skipped_paths or plan.errors):
+ lines.append(" (nothing to do)")
+ lines.append("")
+ else:
+ lines.append("Next steps:")
+ lines.append(" 1. Run the Hermes commands above to deregister the MCP server and plugin.")
+ lines.append(" 2. Re-run with --apply-local to remove the machine-local config directory.")
+ lines.append(" 3. Delete the vault yourself if and only if you really want to lose your notes.")
+ lines.append("")
+
+ return "\n".join(lines).rstrip() + "\n"
+
+
+def iter_hermes_commands() -> Iterable[str]:
+ """Public iterator over the Hermes commands the user should run."""
+
+ return iter(HERMES_COMMANDS)
diff --git a/tests/test_uninstall.py b/tests/test_uninstall.py
new file mode 100644
index 00000000..ccd41b09
--- /dev/null
+++ b/tests/test_uninstall.py
@@ -0,0 +1,328 @@
+import os
+import re
+import sys
+import tempfile
+import textwrap
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from open_second_brain.uninstall import (
+ HERMES_COMMANDS,
+ PLUGIN_NAME,
+ SAFE_CONFIG_DIR_NAMES,
+ plan_uninstall,
+ render_plan,
+)
+from tests.test_cli import run_cli
+
+
+class HermesCommandsTests(unittest.TestCase):
+ def test_hermes_commands_match_documented_form(self):
+ self.assertEqual(
+ HERMES_COMMANDS,
+ (
+ f"hermes mcp remove {PLUGIN_NAME}",
+ f"hermes plugins remove {PLUGIN_NAME}",
+ "hermes gateway restart",
+ ),
+ )
+
+ def test_hermes_commands_do_not_use_quoted_args_blob(self):
+ for cmd in HERMES_COMMANDS:
+ self.assertNotIn("'", cmd)
+ self.assertNotIn('"', cmd)
+ self.assertNotIn("--args ", cmd)
+
+
+class PlanUninstallTests(unittest.TestCase):
+ def test_dry_run_does_not_remove_config_directory(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ config_dir = Path(tmp) / "open-second-brain"
+ config_dir.mkdir()
+ config = config_dir / "config.yaml"
+ config.write_text("vault_path: /vault/example\n", encoding="utf-8")
+ other = config_dir / "snapshot.json"
+ other.write_text("{}", encoding="utf-8")
+
+ plan = plan_uninstall(config_path=config, apply_local=False)
+
+ self.assertFalse(plan.apply_local)
+ self.assertTrue(config.exists())
+ self.assertTrue(other.exists())
+ self.assertTrue(config_dir.is_dir())
+ self.assertEqual(plan.removed_paths, ())
+ self.assertEqual(plan.skipped_paths, ())
+ self.assertEqual(plan.config_dir, config_dir)
+ self.assertTrue(plan.config_dir_exists)
+ self.assertEqual(plan.vault_path, Path("/vault/example"))
+
+ def test_dry_run_records_missing_config(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ config = Path(tmp) / "open-second-brain" / "missing.yaml"
+
+ plan = plan_uninstall(config_path=config, apply_local=False)
+
+ self.assertFalse(plan.config_exists)
+ self.assertFalse(plan.config_dir_exists)
+ self.assertEqual(plan.removed_paths, ())
+
+ def test_apply_local_removes_only_named_config_directory(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ config_dir = Path(tmp) / "open-second-brain"
+ config_dir.mkdir()
+ (config_dir / "config.yaml").write_text("instance: x\n", encoding="utf-8")
+ (config_dir / "snapshots").mkdir()
+ (config_dir / "snapshots" / "old.json").write_text("{}", encoding="utf-8")
+
+ plan = plan_uninstall(config_path=config_dir / "config.yaml", apply_local=True)
+
+ self.assertTrue(plan.apply_local)
+ self.assertFalse(config_dir.exists())
+ self.assertEqual(plan.removed_paths, (config_dir,))
+ self.assertEqual(plan.skipped_paths, ())
+ self.assertEqual(plan.errors, ())
+
+ def test_apply_local_refuses_unknown_directory_name(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ config_dir = Path(tmp) / "etc"
+ config_dir.mkdir()
+ payload = config_dir / "important.yaml"
+ payload.write_text("vault_path: /vault\n", encoding="utf-8")
+
+ plan = plan_uninstall(config_path=payload, apply_local=True)
+
+ self.assertTrue(config_dir.exists())
+ self.assertTrue(payload.exists())
+ self.assertEqual(plan.removed_paths, ())
+ self.assertEqual(len(plan.skipped_paths), 1)
+ skipped_path, reason = plan.skipped_paths[0]
+ self.assertEqual(skipped_path, config_dir)
+ self.assertIn("not a recognized", reason)
+
+ def test_apply_local_refuses_paths_inside_hermes(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ hermes_root = Path(tmp) / ".hermes"
+ config_dir = hermes_root / "open-second-brain"
+ config_dir.mkdir(parents=True)
+ payload = config_dir / "config.yaml"
+ payload.write_text("vault_path: /vault\n", encoding="utf-8")
+
+ plan = plan_uninstall(config_path=payload, apply_local=True)
+
+ self.assertTrue(config_dir.exists())
+ self.assertTrue(payload.exists())
+ self.assertEqual(plan.removed_paths, ())
+ self.assertEqual(len(plan.skipped_paths), 1)
+ _, reason = plan.skipped_paths[0]
+ self.assertIn("Hermes", reason)
+
+ def test_apply_local_refuses_git_repository(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ config_dir = Path(tmp) / "open-second-brain"
+ config_dir.mkdir()
+ (config_dir / ".git").mkdir()
+ payload = config_dir / "config.yaml"
+ payload.write_text("instance: x\n", encoding="utf-8")
+
+ plan = plan_uninstall(config_path=payload, apply_local=True)
+
+ self.assertTrue(config_dir.exists())
+ self.assertEqual(plan.removed_paths, ())
+ self.assertEqual(len(plan.skipped_paths), 1)
+ _, reason = plan.skipped_paths[0]
+ self.assertIn("git", reason)
+
+ def test_apply_local_skips_when_config_dir_missing(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ payload = Path(tmp) / "open-second-brain" / "config.yaml"
+
+ plan = plan_uninstall(config_path=payload, apply_local=True)
+
+ self.assertEqual(plan.removed_paths, ())
+ self.assertEqual(len(plan.skipped_paths), 1)
+ _, reason = plan.skipped_paths[0]
+ self.assertIn("does not exist", reason)
+
+
+class VaultSafetyTests(unittest.TestCase):
+ def test_apply_local_never_touches_vault(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ vault = tmp_path / "vault"
+ (vault / "AI Wiki").mkdir(parents=True)
+ (vault / "Daily").mkdir(parents=True)
+ (vault / "AI Wiki" / "page.md").write_text("# Page\n", encoding="utf-8")
+ (vault / "Daily" / "2026.05.06.md").write_text("# Daily\n", encoding="utf-8")
+
+ config_dir = tmp_path / "open-second-brain"
+ config_dir.mkdir()
+ config = config_dir / "config.yaml"
+ config.write_text(f"vault_path: {vault}\n", encoding="utf-8")
+
+ plan_uninstall(config_path=config, apply_local=True)
+
+ self.assertTrue(vault.is_dir())
+ self.assertTrue((vault / "AI Wiki" / "page.md").is_file())
+ self.assertTrue((vault / "Daily" / "2026.05.06.md").is_file())
+
+ def test_apply_local_never_touches_hermes_config_file(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ hermes_dir = tmp_path / ".hermes"
+ hermes_dir.mkdir()
+ hermes_config = hermes_dir / "config.yaml"
+ hermes_payload = textwrap.dedent(
+ """
+ mcp_servers:
+ open-second-brain:
+ command: o2b
+ args: ["mcp", "--vault", "/vault"]
+ """
+ ).strip() + "\n"
+ hermes_config.write_text(hermes_payload, encoding="utf-8")
+
+ config_dir = tmp_path / "open-second-brain"
+ config_dir.mkdir()
+ config = config_dir / "config.yaml"
+ config.write_text("vault_path: /vault\n", encoding="utf-8")
+
+ plan_uninstall(config_path=config, apply_local=True)
+
+ self.assertTrue(hermes_config.is_file())
+ self.assertEqual(hermes_config.read_text(encoding="utf-8"), hermes_payload)
+
+
+class RenderPlanTests(unittest.TestCase):
+ def _basic_plan(self, *, apply_local: bool, tmp_path: Path) -> str:
+ config_dir = tmp_path / "open-second-brain"
+ config_dir.mkdir()
+ config = config_dir / "config.yaml"
+ config.write_text("vault_path: /vault/here\n", encoding="utf-8")
+
+ plan = plan_uninstall(config_path=config, apply_local=apply_local)
+ return render_plan(plan)
+
+ def test_rendered_plan_includes_hermes_commands(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))
+ for cmd in HERMES_COMMANDS:
+ self.assertIn(cmd, text)
+
+ def test_rendered_plan_states_vault_is_preserved(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))
+ self.assertRegex(text, r"Vault \(NEVER removed by this tool\)")
+ self.assertIn("Daily/", text)
+ self.assertIn("AI Wiki/", text)
+
+ def test_rendered_plan_states_hermes_config_is_not_edited(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))
+ self.assertIn("~/.hermes/config.yaml", text)
+ self.assertIn("never edits", text)
+
+ def test_rendered_plan_marks_dry_run(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ text = self._basic_plan(apply_local=False, tmp_path=Path(tmp))
+ self.assertIn("dry-run", text)
+
+ def test_rendered_plan_marks_apply_local(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ text = self._basic_plan(apply_local=True, tmp_path=Path(tmp))
+ self.assertIn("apply-local", text)
+
+
+class CliUninstallTests(unittest.TestCase):
+ def test_cli_dry_run_does_not_modify_filesystem(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ config_dir = tmp_path / "open-second-brain"
+ config_dir.mkdir()
+ config = config_dir / "config.yaml"
+ config.write_text("vault_path: /vault\n", encoding="utf-8")
+
+ result = run_cli("uninstall", "--config", str(config))
+
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("Uninstall plan", result.stdout)
+ self.assertIn("dry-run", result.stdout)
+ self.assertIn("hermes mcp remove open-second-brain", result.stdout)
+ self.assertIn("hermes plugins remove open-second-brain", result.stdout)
+ self.assertIn("hermes gateway restart", result.stdout)
+ self.assertIn("NEVER removed by this tool", result.stdout)
+ self.assertTrue(config.exists())
+ self.assertTrue(config_dir.is_dir())
+
+ def test_cli_apply_local_removes_only_local_config_dir(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ vault = tmp_path / "vault"
+ (vault / "Daily").mkdir(parents=True)
+ (vault / "Daily" / "2026.05.06.md").write_text("vault content", encoding="utf-8")
+
+ config_dir = tmp_path / "open-second-brain"
+ config_dir.mkdir()
+ config = config_dir / "config.yaml"
+ config.write_text(f"vault_path: {vault}\n", encoding="utf-8")
+
+ result = run_cli("uninstall", "--config", str(config), "--apply-local")
+
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("apply-local", result.stdout)
+ self.assertFalse(config_dir.exists())
+ self.assertTrue(vault.is_dir())
+ self.assertTrue((vault / "Daily" / "2026.05.06.md").is_file())
+
+ def test_cli_apply_local_refuses_when_config_dir_name_unknown(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ config_dir = tmp_path / "etc"
+ config_dir.mkdir()
+ (config_dir / "very-important.yaml").write_text("keep-me\n", encoding="utf-8")
+ config = config_dir / "config.yaml"
+ config.write_text("vault_path: /vault\n", encoding="utf-8")
+
+ result = run_cli("uninstall", "--config", str(config), "--apply-local")
+
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("skipped", result.stdout)
+ self.assertTrue(config_dir.is_dir())
+ self.assertTrue((config_dir / "very-important.yaml").is_file())
+
+ def test_cli_uses_open_second_brain_config_env(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ tmp_path = Path(tmp)
+ config_dir = tmp_path / "open-second-brain"
+ config_dir.mkdir()
+ config = config_dir / "config.yaml"
+ config.write_text("vault_path: /env/vault\n", encoding="utf-8")
+
+ result = run_cli(
+ "uninstall",
+ env={"OPEN_SECOND_BRAIN_CONFIG": str(config)},
+ )
+
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn(str(config), result.stdout)
+ self.assertIn("/env/vault", result.stdout)
+
+ def test_cli_help_documents_safety_invariants(self):
+ result = run_cli("uninstall", "--help")
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("never touches", result.stdout)
+ self.assertIn("vault", result.stdout.lower())
+
+
+class SafeNamesTests(unittest.TestCase):
+ def test_safe_names_only_contain_canonical_open_second_brain_names(self):
+ self.assertEqual(
+ SAFE_CONFIG_DIR_NAMES,
+ frozenset({"open-second-brain", "open_second_brain"}),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()