TROVE

TROVE is a macOS-only, local-private capability runtime. It returns bounded cited evidence to external Agents and can optionally run a local Reply Runtime that generates, reviews, and delivers replies through verified source Providers. Reply delivery is disabled by default. MCP is the primary Agent interface and the CLI is the recovery and operator interface.

The product is TROVE. WeChat support is an optional source Provider rather than the product identity.

Install

From a verified release artifact directory:

python3 -m venv "$HOME/.local/share/trove/runtime"
"$HOME/.local/share/trove/runtime/bin/pip" install ./trove_runtime-1.0.0-py3-none-any.whl ./trove_provider_*.whl
export PATH="$HOME/.local/share/trove/runtime/bin:$PATH"
trove version

Keep the artifact directory and Vault owner-only. Create or select a Vault, then run the redacted health check. The explicit path avoids hidden discovery.

export TROVE_VAULT_ROOT="$HOME/Trove/trove-vault"
mkdir -p "$TROVE_VAULT_ROOT"
chmod 700 "$TROVE_VAULT_ROOT"
trove --vault "$TROVE_VAULT_ROOT" doctor

Connect MCP

Register trove-mcp through Agent Switch with these arguments:

--pack standard --vault $TROVE_VAULT_ROOT

Run agent-switch doctor before changing its central configuration and agent-switch reconcile afterward. Do not hand-edit generated client configs. The standard pack is sufficient for ordinary recall and search.

Without Agent Switch

Register the installed trove-mcp directly in each client (a source checkout uses .venv/bin/trove-mcp). Claude Code:

claude mcp add trove -- "$HOME/.local/share/trove/runtime/bin/trove-mcp" --pack standard --vault "$TROVE_VAULT_ROOT"

Codex, which writes [mcp_servers.trove] in ~/.codex/config.toml:

codex mcp add trove -- "$HOME/.local/share/trove/runtime/bin/trove-mcp" --pack standard --vault "$TROVE_VAULT_ROOT"

Install the canonical Skills with bash scripts/install_skills.sh; it links skills/* into ~/.agents/skills, accepts --target DIR, and --uninstall removes only those links.

Secret values resolve only through Agent Switch; environment variables enable providers and select secret names but never carry values. Local embedding and every Vault read work without it. Cloud providers and source Provider key capture require Agent Switch (github.com/JNHFlow21/agent-switch).

First call

Ask the Agent to call trove_recall, or use the exact CLI fallback:

trove --vault "$TROVE_VAULT_ROOT" recall --target "Example person" --limit 50

The JSON envelope states ok, typed errors, citations, and coverage. Follow an opaque cursor only when the requested coverage needs another page.

Failure path

Run trove --vault "$TROVE_VAULT_ROOT" doctor. Retry only when error.retryable is true. For ambiguous_target, select one returned account. For approval_required, stop: an Agent can request or inspect approval but only a human at the controlling terminal can decide it.

See MCP, operations, and the generated capability reference. Provider setup is separate; see the installed source Provider. The optional Reply Runtime architecture and safety model are documented in Reply Runtime.

Privacy boundary

Real chat databases, exports, media, transcripts, provider payloads, secrets, logs, and local Vault data do not belong in this repository. Tests and checked-in evidence must be synthetic or explicitly source-safe. Run the privacy scanner before every commit.

See open-source privacy and security policy.

Contributing

See CONTRIBUTING.md. TROVE is licensed under Apache License 2.0.