TROVE

TROVE is not a general-purpose autonomous agent and it is not a hosted chat database. It is a local capability runtime: external agents ask for recall, search, context, or a controlled operation; TROVE returns a typed, size-bounded result with citations and coverage metadata.

The product is TROVE. WeChat is one optional source Provider, not the product identity.

Why TROVE

Related MCP server: macOS Companion MCP Server

Architecture

flowchart LR
  A["Codex / Claude Code / MCP client"] --> M["trove-mcp"]
  O["Local operator"] --> C["trove CLI"]
  M --> L["Shared client"]
  C --> L
  L -->|"trove/1 over owner-only Unix socket"| D["troved"]
  D --> K["Capability catalog + dispatcher"]
  K --> V["Private local Vault + indexes"]
  K --> P["Verified source Provider"]
  P --> W["Optional WeChat source"]
  D --> R["Optional Reply Runtime — off by default"]
  O -->|"exact local decision"| R
  R --> P

There is no public network listener. One canonical Vault maps to one daemon. The CLI and MCP adapter use the same protocol, catalog, validation, and dispatcher, so the recovery path and agent path cannot silently diverge.

Core capabilities

• Bounded recall and search — result limits, response budgets, opaque cursors, coverage metadata, and stable citations.

• Local-first storage — Vault data, indexes, caches, and operation journals stay under an owner-controlled path outside this repository.

• Agent-native MCP — cumulative standard, operations, and admin packs; use the smallest pack that completes the task.

• Typed failure semantics — retry only when error.retryable is true; ambiguity and incomplete coverage are explicit.

• Provider boundary — source integrations implement a verified contract; WeChat support is independently packaged.

• Human-controlled actions — approval decisions require an interactive controlling terminal. MCP and background jobs cannot approve themselves.

• Privacy gates — synthetic fixture rules, current-tree scanning, full Git history scanning with Gitleaks, and CI checks on every push and pull request.

Quick start from source

Requirements

• macOS

• Python 3.11 or newer

• Git

Clone the public source and install the lightweight base runtime:

git clone https://github.com/JNHFlow21/trove.git
cd trove
TROVE_RUNTIME_INSTALL_EXTRAS="" bash scripts/bootstrap_runtime.sh

Create an owner-only Vault outside the source checkout and run the redacted health check:

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

The default macOS bootstrap additionally supports local-vision,local-embedding,zvec. See testing before installing optional local ASR, VLM, key-capture, or cloud-retrieval extras.

Connect an MCP client

Register the installed trove-mcp through Agent Switch with:

--pack standard --vault $TROVE_VAULT_ROOT

Run agent-switch doctor before changing central tool configuration and agent-switch reconcile afterward. Do not copy credentials into native client configuration. Ask the agent to call trove_recall, or use the recovery CLI:

.venv/bin/trove --vault "$TROVE_VAULT_ROOT" recall \
  --target "Example person" --limit 50

Follow a returned cursor only when the task needs more coverage. Stop on complete coverage, no_results, or a terminal error.

Privacy and safety boundary

The public repository contains source code, schemas, public documentation, and synthetic tests only. It must never contain real chats, contacts, account IDs, media, transcripts, OCR, provider payloads, local Vaults, logs, credentials, machine-specific paths, or evidence from real runs.

./scripts/trove-python scripts/privacy_scan.py .
./scripts/trove-python scripts/check.py contract
gitleaks git --redact

The scanners are guardrails, not a substitute for human review. See Open-source privacy and the Security Policy.

Repository map

Documentation

• Architecture

• MCP packs and trust boundary

• Capability reference

• Protocol

• Provider SDK

• WeChat Provider

• Operations and recovery

• Testing

• Release model

• Changelog

• Roadmap

Project activity

Traffic snapshot: 2026-08-10. GitHub exposes clone and unique-visitor analytics only to maintainers, so those values are a dated, transparent snapshot rather than a token-backed public badge.

Clone activity

The curve shows cumulative clones inside GitHub's rolling 14-day Traffic window. The Traffic series is a dated aggregate owner snapshot; stars, forks, and commits in the side cards refresh after every new star and weekly. No long-lived token is embedded in this README.

Contributing

Read CONTRIBUTING.md before opening a pull request. Privacy regressions and changes that weaken the application or approval boundaries will not be accepted. Please report vulnerabilities through GitHub private vulnerability reporting rather than a public issue.

License

Apache License 2.0 © 2026 TROVE contributors