Hermes-Native Memory Console Plan

Executive Summary

The right product is a Hermes-native memory console: a local dashboard tab for finding, inspecting, and cleaning Mnemosyne memories across Hermes profiles.

MCP is the wrong abstraction for this job. The Hermes dashboard already provides the extension surface needed: a dashboard plugin with a React bundle, plugin CSS, and a FastAPI router mounted at /api/plugins/<name>/.

1. Keep the plugin as a drop-in Hermes dashboard plugin.
2. Keep the backend as direct FastAPI routes over profile-scoped Mnemosyne SQLite databases.
3. Keep the frontend as one focused console: find → inspect → act.
4. Keep graph data read-only until graph mutation semantics are designed.
5. Keep every mutation reversible by default: edit, expire, supersede, and bulk metadata changes before hard delete.

Documentation Review Findings

Product Definition

Current Baseline

The repo already has the right foundation:

• standalone plugin repo
• Hermes dashboard manifest
• frontend bundle and CSS
• FastAPI backend router
• profile-aware Mnemosyne DB resolution
• profile traversal rejection
• health endpoint
• memory list/search/filter/sort
• safe edit, create, expire, supersede
• facts and triples endpoints
• cleanup lenses, bulk mutation, lint/risk scoring
• pytest coverage for profile isolation and backend safety

Target UX

Mnemosyne
Manage memory records across profiles.        Profile: default   Refresh

[Needs attention] [Working] [Episodic] [Facts] [Triples]

Search memories…                              [All] [Durable] [Session] [Temporary] [Unknown]

┌─────────────────────────────────────┬─────────────────────────────────────┐
│ Memory inbox                        │ Inspector                           │
│ Issue  Temporary task state         │ Content                             │
│ session · conversation · May 15     │ ...                                 │
│ Durable  User preference            │ Metadata                            │
│ global · preference · May 14        │ source · scope · importance         │
│                                     │ Actions                             │
│                                     │ [Edit] [Expire] [Copy ID]           │
└─────────────────────────────────────┴─────────────────────────────────────┘

Architecture

Hermes Dashboard
  └── Mnemosyne plugin tab `/mnemosyne`
        ├── dashboard/manifest.json
        ├── dashboard/dist/index.js
        ├── dashboard/dist/style.css
        └── dashboard/plugin_api.py
              └── profile-scoped SQLite reads/writes
                    ├── ~/.hermes/mnemosyne/data/mnemosyne.db
                    └── ~/.hermes/profiles/<profile>/mnemosyne/data/mnemosyne.db

1. No MCP. This is a dashboard plugin, not an agent tool integration.
2. No silent profile fallback. Named profiles must resolve to their own DB or return an error.
3. Whitelisted tables only. Memory table names remain constrained.
4. Parameterized SQL values. No interpolated user values in SQL predicates.
5. Validated writes only. Mutation routes validate fields, ranges, JSON, and profile.
6. Facts/triples read-only. Graph mutation waits for a separate design.

Implementation Plan

Phase 1 — Native Plugin Alignment

• Verify manifest fields and setup path.
• Document rescan versus dashboard restart behavior.
• Remove MCP setup language from plan and README.

Phase 2 — Backend Contract Hardening

• Confirm attention=true filtering and correct totals.
• Keep facts/triples read-only.
• Test profile isolation, traversal rejection, invalid tables, invalid sort keys, invalid JSON, and bulk mutation boundaries.

Phase 3 — Memory Console UI Redesign

• Simplify header and profile controls.
• Replace large cards with segmented navigation.
• Redesign rows as inbox items.
• Redesign inspector into Content, Metadata, Actions, Replace, Raw JSON.
• Keep edit mode inline.

Phase 4 — Cleanup Workflows

• Use deterministic cleanup lenses.
• Support previewed bulk actions.
• Keep bulk writes profile-scoped.
• Exclude hard delete from this phase.

Phase 5 — Verification and Release

cd /Users/huntsyea/.hermes/hermes-agent
python -m pytest /Users/huntsyea/Dev/hermes-mnemosyne-dashboard/tests/plugins/test_mnemosyne_dashboard_plugin.py -q -o 'addopts='

cd /Users/huntsyea/Dev/hermes-mnemosyne-dashboard
node --check dashboard/dist/index.js
python -m py_compile dashboard/plugin_api.py

Backend Contract

GET  /profiles
GET  /health?profile=<name>
GET  /memories?profile=<name>&table=<working_memory|episodic_memory>&q=&state=&sort=&limit=&offset=&attention=
GET  /memories/{table}/{id}?profile=<name>
PATCH /memories/{table}/{id}?profile=<name>
POST /memories?profile=<name>
POST /memories/{table}/{id}/expire?profile=<name>
POST /memories/{table}/{id}/supersede?profile=<name>
POST /bulk?profile=<name>
GET  /facts?profile=<name>
GET  /triples?profile=<name>
GET  /cleanup/lenses?profile=<name>

Recommended Build Order

1. Update docs and README to state the native dashboard-plugin direction and MCP exclusion.
2. Add backend tests for attention=true and profile safety gaps.
3. Implement/fix backend contract gaps.
4. Redesign the UI shell: header, segmented nav, two-pane layout.
5. Redesign inbox rows and inspector.
6. Tighten cleanup lenses and bulk actions.
7. Add static frontend copy/affordance tests.
8. Run full verification.
9. Smoke the live dashboard.
10. Commit as one coherent product-direction update for docs-only work; split test/backend/frontend commits once implementation begins.

Definition of Done

• The dashboard tab feels native to Hermes.
• Hunter can manage memories without learning MCP.
• Profile selection is explicit and safe.
• Memory cleanup starts from Needs attention.
• Editing, expiring, superseding, and bulk cleanup are obvious.
• Facts and triples are clearly read-only.
• Tests and live smoke checks pass.
• Documentation matches the implementation path.