Agent TUI: browse, search, inspect, and remove Mentra memories #137

New Issue

hugo · 2026-08-22T09:40:21Z

hugo commented

2026-08-22 09:40:21 +00:00

Goal

Add an operator-only TUI memory browser for the agent's durable Mentra memories. It must support complete browsing, text search, record inspection, and deletion without asking the conversational model to administer its own storage.

Current state and Mentra discovery

MetaCrate currently gives authorized avatar agents Mentra's memory_search, memory_pin, and memory_forget tools, but the TUI has no memory view.

Mentra 0.18.3 already provides the correct record and mutation semantics:

MemorySearchRequest scopes every query to an agent_id and supports query, result limit, character budget, and search mode.
MemoryHit exposes record ID, kind, content, source revision, creation time, metadata, source, retrieval reason, and score.
MemoryEngine::forget(agent_id, record_id) performs a namespace-checked tombstone; the model-facing memory_forget uses the same behavior.
HybridRuntimeStore is cloneable, so MetaCrate can retain a host-side handle while giving a clone to Runtime::builder().with_store(...).

The missing Mentra capability is a host-facing list/browse API. MemoryStore can search and tombstone records, but it cannot enumerate an agent's records with stable cursor pagination or filters; an empty/full-text query is not a reliable substitute. Do not query Mentra's SQLite schema directly. Add or adopt a Mentra API such as bounded list_records(agent_id, cursor, filters) and keep the storage schema owned by Mentra.

Design

Persist an explicit mapping from authenticated avatar identity/logical agent to the Mentra agent_id; do not infer identity from versioned agent names.
Retain the HybridRuntimeStore/Mentra memory facade in the runtime owner and expose bounded operator methods through MetaCrate's control plane.
Add paged requests for memory agents, browse, search, record detail, and forget.
Support filters for record kind (episode, summary, fact), pinned/source, and creation range, plus stable sort by newest/oldest/relevance as applicable.
Show content and provenance only to the operator role. Observer tokens get counts/health only, not memory text.
Delete through Mentra's namespaced tombstone operation, require confirmation in the TUI, audit the agent/record IDs and outcome without copying memory content into logs, and refresh search/browse results immediately.
Keep page size, query bytes, returned content, concurrent operations, and total control-frame size bounded. No model inference is involved in browsing or deletion.

Acceptance criteria

The TUI can select a logical agent/avatar, browse every non-tombstoned memory through stable pagination, search arbitrary text, filter/sort records, and open full bounded record details.
Deleting a selected record tombstones only that agent's record; cross-agent IDs fail closed and the record disappears from both browse and search after restart.
Pinned facts, automatic episodes, and compaction summaries display their distinct kinds and provenance.
Observer access cannot retrieve content or delete records; operator mutations are confirmed and audited.
Tests cover pagination stability, punctuation/empty searches, concurrent ingest during browsing, restart persistence, tombstones, cross-agent isolation, and maximum-size records/control frames.

No implementation is part of this issue creation pass.

## Goal Add an operator-only TUI memory browser for the agent's durable Mentra memories. It must support complete browsing, text search, record inspection, and deletion without asking the conversational model to administer its own storage. ## Current state and Mentra discovery MetaCrate currently gives authorized avatar agents Mentra's `memory_search`, `memory_pin`, and `memory_forget` tools, but the TUI has no memory view. Mentra 0.18.3 already provides the correct record and mutation semantics: - `MemorySearchRequest` scopes every query to an `agent_id` and supports query, result limit, character budget, and search mode. - `MemoryHit` exposes record ID, kind, content, source revision, creation time, metadata, source, retrieval reason, and score. - `MemoryEngine::forget(agent_id, record_id)` performs a namespace-checked tombstone; the model-facing `memory_forget` uses the same behavior. - `HybridRuntimeStore` is cloneable, so MetaCrate can retain a host-side handle while giving a clone to `Runtime::builder().with_store(...)`. The missing Mentra capability is a host-facing list/browse API. `MemoryStore` can search and tombstone records, but it cannot enumerate an agent's records with stable cursor pagination or filters; an empty/full-text query is not a reliable substitute. Do not query Mentra's SQLite schema directly. Add or adopt a Mentra API such as bounded `list_records(agent_id, cursor, filters)` and keep the storage schema owned by Mentra. ## Design - Persist an explicit mapping from authenticated avatar identity/logical agent to the Mentra `agent_id`; do not infer identity from versioned agent names. - Retain the `HybridRuntimeStore`/Mentra memory facade in the runtime owner and expose bounded operator methods through MetaCrate's control plane. - Add paged requests for memory agents, browse, search, record detail, and forget. - Support filters for record kind (`episode`, `summary`, `fact`), pinned/source, and creation range, plus stable sort by newest/oldest/relevance as applicable. - Show content and provenance only to the operator role. Observer tokens get counts/health only, not memory text. - Delete through Mentra's namespaced tombstone operation, require confirmation in the TUI, audit the agent/record IDs and outcome without copying memory content into logs, and refresh search/browse results immediately. - Keep page size, query bytes, returned content, concurrent operations, and total control-frame size bounded. No model inference is involved in browsing or deletion. ## Acceptance criteria - The TUI can select a logical agent/avatar, browse every non-tombstoned memory through stable pagination, search arbitrary text, filter/sort records, and open full bounded record details. - Deleting a selected record tombstones only that agent's record; cross-agent IDs fail closed and the record disappears from both browse and search after restart. - Pinned facts, automatic episodes, and compaction summaries display their distinct kinds and provenance. - Observer access cannot retrieve content or delete records; operator mutations are confirmed and audited. - Tests cover pagination stability, punctuation/empty searches, concurrent ingest during browsing, restart persistence, tombstones, cross-agent isolation, and maximum-size records/control frames. No implementation is part of this issue creation pass.

hugo added this to the 14 - metacrate grid agent milestone 2026-08-22 09:40:21 +00:00

hugo added the enhancement label 2026-08-22 10:53:50 +00:00

hugo referenced this issue

2026-08-23 10:47:19 +00:00

Rebuild the grid-agent operator TUI with Ratatui dashboards #140

hugo commented

2026-08-23 17:19:12 +00:00

Implemented in 360203d and pushed to main.

Completed the operator-only Mentra memory administration loop: vendored Mentra 0.18.3 now owns bounded stable list/detail/count and filtered-search APIs across its hybrid, SQLite, and volatile stores; MetaCrate persists an explicit authenticated-avatar/logical-agent/Mentra-ID mapping; control requests cover aggregate health, agent paging, browse/search/filter/sort/detail/forget; observer content access fails closed; forget is namespaced, confirmed, content-free audited, and immediately refreshes the active TUI page. The Ratatui Memory screen exposes agent selection, stable paging, arbitrary/empty/punctuation search, kind/pinned/source/time filters, provenance, bounded details, and deletion.

Focused gates green:

strict Clippy for metacrate-grid-agent all targets + live-grid
strict Clippy for vendored Mentra
Mentra stable pagination/filter/concurrent-ingest/restart/tombstone/max-page test
MetaCrate mapping persistence/cross-agent isolation test
production control role/bounded-frame/empty+punctuation search test
TUI memory request/render/confirmation test
dependency policy: 7/7
deterministic acceptance gate: 2/2
rustdoc with warnings denied

The pre-existing default-feature dead_code warning in vision.rs is outside this issue; the required live-grid strict Clippy gate is clean.

Implemented in 360203d and pushed to main. Completed the operator-only Mentra memory administration loop: vendored Mentra 0.18.3 now owns bounded stable list/detail/count and filtered-search APIs across its hybrid, SQLite, and volatile stores; MetaCrate persists an explicit authenticated-avatar/logical-agent/Mentra-ID mapping; control requests cover aggregate health, agent paging, browse/search/filter/sort/detail/forget; observer content access fails closed; forget is namespaced, confirmed, content-free audited, and immediately refreshes the active TUI page. The Ratatui Memory screen exposes agent selection, stable paging, arbitrary/empty/punctuation search, kind/pinned/source/time filters, provenance, bounded details, and deletion. Focused gates green: - strict Clippy for metacrate-grid-agent all targets + live-grid - strict Clippy for vendored Mentra - Mentra stable pagination/filter/concurrent-ingest/restart/tombstone/max-page test - MetaCrate mapping persistence/cross-agent isolation test - production control role/bounded-frame/empty+punctuation search test - TUI memory request/render/confirmation test - dependency policy: 7/7 - deterministic acceptance gate: 2/2 - rustdoc with warnings denied The pre-existing default-feature dead_code warning in vision.rs is outside this issue; the required live-grid strict Clippy gate is clean.

hugo closed this issue

2026-08-23 17:19:12 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#137