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.
Variant 1: Independent additive layers
- Approach: Implement each of the three tasks in its own seam with no shared abstraction. The runtime capability check becomes a thin predicate wrapper around
buildToolTableinserver.ts; the--jsonwork adds an inheritableFlagSpecplus a newsrc/cli/json-helpers.ts; completions ship as a generator that walks each command's existingFlagsSchema. Nothing is unified - three small, independently revertible additions. - Trade-offs:
- Pro: smallest blast radius; each piece is independently testable and revertible.
- Pro: respects the "small, dependency-free CLI grammar" convention with minimal disruption.
- Pro: capability layer stays additive on top of static scope, easy to keep transparent.
- Con: three sources of truth - the completion generator must re-walk command schemas and can drift from real flags unless carefully wired (tension with the anti-drift constraint).
- Con: no synergy; the
--jsondiscovery contract and completions duplicate command-metadata traversal.
- Complexity: medium
- Risk: low
Variant 2: Single declarative manifest spine
- Approach: Introduce one declarative registry describing both MCP tools (scope plus runtime capability predicates) and CLI commands (flags, including an inherited
--json). The runtime capability filter, the shell-completion generator, and the JSON-envelope contract all derive from this single manifest, sohelp --json,completions, and tool exposure share one source of truth. - Trade-offs:
- Pro: anti-drift by construction - completions and help cannot diverge from declared flags (directly satisfies the registry/manifest constraint).
- Pro: agent-discoverable surface (
help --jsonenumerates every command/flag) and a coherent capability model across CLI and MCP. - Con: large refactor touching
argparse, every CLI verb,tools.ts, andserver.ts; high chance of brushing against public-API backward-compat constraints. - Con: over-engineers two priority-1 ergonomic tasks by coupling them to the design-heavy capability system that the board says needs an ADR first.
- Con: a single registry change has wide blast radius and harder review.
- Complexity: large
- Risk: high
Variant 3: Phased - shared CLI registry now, ADR-gated capability layer
- Approach: Ship the two priority-1 ergonomic tasks together this PR behind a shared CLI command manifest (used both by the inheritable
--jsonflag +json-helpers.tsand by the completion generator, so they cannot drift), scoped to the CLI only. Land the runtime capability verification as a separate, transparent layer that wraps staticToolScopewith a capability predicate plus a probe/diagnostic path, designed ADR-first and kept minimal in this scope. - Trade-offs:
- Pro: matches the actual priorities (1/1/3) and the board's "needs an ADR before build" note for the capability system.
- Pro: one shared CLI manifest covers
--jsonand completions without dragging MCP into the refactor, satisfying the anti-drift constraint where it matters. - Pro: capability filtering stays additive on top of static scope with an explicit probe (satisfies "no silent hiding of tools").
- Con: two registries (CLI command manifest + MCP capability predicates) rather than one unified spine.
- Con: the capability piece may land partially or as a thin first cut, deferring full dynamism.
- Complexity: medium
- Risk: low
Recommended: Variant 3
Rationale: It honors the triage reality - two ergonomic priority-1 tasks that are cheap and a priority-3 capability system the board explicitly says needs an ADR before build - instead of forcing them into one coupled abstraction as Variant 2 does. The shared CLI manifest captures the real synergy (completions + --json from one source of truth, satisfying the anti-drift constraint) that Variant 1 misses, while keeping the capability layer additive, transparent via a probe path, and on top of static scope as the constraints require. This sequencing keeps the core deterministic and dependency-light while letting the design-heavy piece mature behind an ADR rather than blocking the easy wins.