> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase18-session01-memory-upgrade-write/spec.md).

# Session Specification

**Session ID**: `phase18-session01-memory-upgrade-write` **Phase**: 18 - Hermes Memory And Visualization **Status**: Completed **Created**: 2026-06-02

***

## 1. Session Overview

This session upgrades the Hermes Memory tab from three simple read-only excerpts into the v2.3 parity memory surface: three manuscript-style memory layers, bounded character-budget rendering, a conversation-history callout, token-gated profile memory grid, and an admin-gated Obsidian vault bridge. Phase 16 already landed the sensitive profile read and the `/__hermes_obsidian` write endpoint, while Phase 17 landed the current Hermes shell, tab framework, and write UI patterns.

The implementation should consume existing hook contracts instead of widening bridge behavior. `useHermes()` already exposes token-gated `memory`, `profiles`, and `sessions` views, and `useHermesAdmin()` already exposes the `obsidian.connectVault()` mutation that sends the required confirmation payload. The Memory tab becomes the user-facing composition layer for those contracts.

This session is the first Phase 18 session and is the prerequisite for the read-only Mnemosyne constellation session. After this plan, the next workflow step is `implement`; validation and PRD updates happen only after implementation is complete.

***

## 2. Objectives

1. Render USER, MEMORY, and SOUL as v2.3-inspired manuscript layers with bounded text, character-budget feedback, template stripping, and resilient empty/error/offline/token states.
2. Add a conversation-history callout and token-gated profile memory grid using existing Hermes hook views without exposing private memory bodies outside the approved Memory surface.
3. Wire an Obsidian bridge UI through `useHermesAdmin().obsidian` with vault-path persistence, explicit confirmation, admin-disabled hints, duplicate-trigger prevention, and bounded success/error feedback.
4. Extend focused component and hook coverage for memory mode states, profile rendering, Obsidian gating, confirmation payloads, and duplicate-trigger behavior.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the Hermes v2.3 guardrail baseline and write-safety contract.
* [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides `/__hermes_profiles` and `/__hermes_obsidian` with loopback, token, admin, allow-list, and confinement protections.
* [x] `phase16-session03-data-layer-demo-fixtures` - Provides typed hook contracts and bounded demo fixtures for Hermes data.
* [x] `phase17-session01-visual-system-shell-status-pill` - Provides the cinematic Hermes shell and local visual primitives.
* [x] `phase17-session02-chat-tab-write` - Establishes current admin write UI and duplicate-trigger patterns.
* [x] `phase17-session03-pantheon-upgrade-write` - Establishes richer Hermes tab composition, admin-gated write copy, and bounded error formatting.

### Required Tools/Knowledge

* React 19, TanStack Query, TanStack Router, Tailwind CSS 4, Radix UI wrappers, and lucide-react.
* Existing Hermes contracts in `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts`.
* Existing hooks in `src/hooks/use-hermes.ts` and `src/hooks/use-hermes-admin.ts`.
* Existing component patterns in `src/components/hermes/hermes-page-primitives.tsx`.
* V23 source anchors in `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.hermes.tsx`.

### Environment Requirements

* Bun 1.3.14 project environment.
* Local dev bridge behavior remains dev-only, loopback-gated, token-gated for sensitive reads, and admin-gated for writes.
* No live Hermes, Obsidian vault, or admin token is required for automated tests; tests should use fixtures/mocks.

***

## 4. Scope

### In Scope (MVP)

* User can inspect three Hermes memory layers - implement USER, MEMORY, and SOUL rendering in `src/components/hermes/hermes-memory-card.tsx` with bounded text, empty fallbacks, and character-budget feedback.
* User can understand raw conversation history separately from curated memory - add a callout derived from the existing sessions view with explicit loading, empty, error, offline, and token-failure states.
* User can inspect profile memory status - render the token-gated profiles view as a compact profile grid with active/model/gateway fallbacks and no raw profile secrets.
* User can connect Hermes memory to an Obsidian vault - use `admin.obsidian.connectVault()` with explicit confirmation, vault-path persistence, admin/token disabled states, duplicate-trigger prevention while in-flight, and state reset on disconnect/reopen.
* Maintainer can verify behavior - update component and hook tests and record focused validation in the session implementation notes.

### Out of Scope (Deferred)

* Mnemosyne 3D constellation - Reason: owned by Phase 18 Session 02 and must be code-split separately.
* Mission Control, Documents Gallery, Connections, and remaining long-tail Hermes sections - Reason: owned by later phases.
* Rewriting `/__hermes_profiles` or `/__hermes_obsidian` bridge internals - Reason: Phase 16 already implemented and tested those endpoints.
* Adding broader Obsidian browsing, editing, file deletion, or vault discovery from the browser - Reason: this session only connects the existing allow-listed vault write.
* Adding new heavy visual dependencies or assets - Reason: current bundle budget remains tight and this session does not need them.

***

## 5. Technical Approach

### Architecture

Keep the implementation centered on `src/components/hermes/hermes-memory-card.tsx`. Extend `HermesReadOnlyPage` to pass the existing `profiles`, `sessions`, and `admin` objects into the Memory card, alongside the current `memory` view and demo mode flag. The component should stay controlled by hook-provided `HermesQueryView` and `UseHermesAdminResult` contracts, with no ad hoc fetch calls in the view layer.

The Memory card should split presentation helpers from render blocks: layer metadata, section splitting, SOUL template/prose cleanup, character-budget percentage, profile status formatting, vault-path persistence, confirmation-state derivation, and sanitized mutation result copy. Obsidian writes must call only `admin.obsidian.connectVault(vaultPath)` after the user provides a non-empty vault path and explicit confirmation.

### Design Patterns

* Contract-first UI: consume existing hook/parser types instead of adding endpoint clients.
* Local guarded writes: disable Obsidian actions when demo mode, offline state, missing token, disabled admin mode, empty vault path, missing confirmation, or in-flight mutation prevents writes.
* Exhaustive states: preserve loading, empty, error, offline, token-failure, success, and demo render paths for memory, sessions, and profiles.
* Bounded output: render sanitized local paths and errors only; do not show raw command output, credentials, or private bridge internals.
* Fixture-first tests: mock hooks/actions in component tests and avoid live Hermes or Obsidian dependencies.

### Technology Stack

* React 19 with TypeScript.
* TanStack Query through existing Hermes hooks.
* Tailwind CSS 4 and existing Hermes primitives.
* lucide-react for icons.
* Vitest and Testing Library for focused component/hook coverage.

***

## 6. Deliverables

### Files to Create

| File                                                                                | Purpose                                                                | Est. Lines |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase18-session01-memory-upgrade-write/implementation-notes.md` | Record implementation decisions, validation commands, and safety notes | \~80       |

### Files to Modify

| File                                                       | Changes                                                                                                          | Est. Lines |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/hermes-memory-card.tsx`             | Three-layer memory UI, conversation callout, profile grid, Obsidian bridge, state handling, accessibility labels | \~450      |
| `src/components/hermes/hermes-read-only-page.tsx`          | Pass sessions, profiles, and admin contracts into Memory                                                         | \~25       |
| `src/lib/hermes-demo-data.ts`                              | Ensure demo profiles support the Memory profile grid path                                                        | \~30       |
| `src/components/hermes/__tests__/hermes-sections.test.tsx` | Add memory layer, profile, Obsidian gating, confirmation, success, and error coverage                            | \~180      |
| `src/hooks/__tests__/use-hermes-admin.test.tsx`            | Add or confirm Obsidian confirmation and duplicate-trigger coverage                                              | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] USER, MEMORY, and SOUL render as distinct manuscript-style layers with bounded content, empty fallbacks, and correct character-budget behavior.
* [ ] SOUL strips template/frontmatter/comment noise where appropriate and does not render a character-budget ring.
* [ ] Conversation history appears as a separate callout from curated memory and handles loading, empty, error, offline, token-failure, success, and demo states.
* [ ] Profile memory grid renders token-gated profile summaries with bounded fallbacks and no raw private content.
* [ ] Obsidian bridge requires admin mode, token availability, a non-empty vault path, and explicit confirmation before calling `connectVault`.
* [ ] Obsidian connect action disables while pending, renders success/error states, and resets confirmation/result state when disconnected or reopened.

### Testing Requirements

* [ ] Component tests cover memory layers, section splitting, SOUL fallback behavior, conversation callout states, profile grid states, and Obsidian bridge states.
* [ ] Component tests cover admin-disabled, token-missing, pending, success, error, and confirmation-disabled Obsidian behavior.
* [ ] Hook/admin tests cover Obsidian confirmation payload and duplicate-trigger prevention when not already covered.
* [ ] Focused tests pass for Hermes components, `useHermesAdmin`, Hermes admin types, and bridge Obsidian safety coverage.
* [ ] Typecheck and lint pass or any unrelated pre-existing failures are documented.

### Non-Functional Requirements

* [ ] Sensitive reads remain token-gated and do not run without the per-run token.
* [ ] Obsidian writes remain loopback, token, admin, allow-list, confirmation, and path-confinement gated.
* [ ] UI does not expose raw command output, credentials, private path fragments beyond existing sanitized labels, or vault contents.
* [ ] Interactions are keyboard-accessible and have labels for controls, profile/status badges, confirmation, and vault path input.
* [ ] Text remains bounded and scannable on mobile and desktop.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] No new global `findtrend` identifiers.
* [ ] No generated private data, credentials, or real vault paths committed.

***

## 8. Implementation Notes

### Key Considerations

* The low-level profile read and Obsidian write contracts already exist. This session should wire UI to them rather than reimplementing endpoint clients.
* The Memory tab is a sensitive local-agent surface, not Trend Finder public evidence. Keep copy and data boundaries under AI OS/Hermes language.
* Existing `X-Claude-OS-Token` compatibility remains part of the bridge contract and should not be renamed in this session.
* The Obsidian bridge writes outside the Hermes home and is therefore the highest-risk part of this session; the UI must stay explicit about admin gating and confirmation.

### Potential Challenges

* Upstream profile-memory details differ from current AI OS profile summaries: Use the current `HermesProfileSummary` contract and render only safe fields already exposed by `/__hermes_profiles`.
* Session count is not part of `HermesMemoryBody`: Derive the conversation callout from the existing sessions view passed by `HermesReadOnlyPage`.
* Obsidian connection state is reopenable local UI state: Persist only lightweight vault-path/connected flags and reset confirmation/results when the user disconnects or changes the vault path.
* Error output can expose local paths: Reuse bounded/sanitized display patterns and never render raw command output.

### Relevant Considerations

* \[P04] **Hermes bridge guardrails must stay intact**: Sensitive reads and opt-in writes depend on loopback + token checks, no-clobber path safety, and disabled-by-default admin mode.
* \[P17] **One write surface per capability**: Keep the Obsidian write owned by the Memory tab and avoid duplicating the same write controls elsewhere.
* \[P17] **Redact and bound high-risk write feedback**: Bound Obsidian success/error output and avoid raw local paths or command details.
* \[P01] **Bundle budget watch on 3D vendor chunks**: Do not add new 3D or heavy visual dependencies in this session.
* \[P09] **Legacy alias migration is still additive**: Preserve existing legacy token/header/storage compatibility contracts unless a separate migration scopes aliases, docs, and tests.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Sensitive profile and memory reads can appear broken if token-failure, offline, and empty states are not handled explicitly.
* Obsidian writes can be double-triggered unless submit controls are disabled while in-flight.
* Reopenable vault-path and confirmation state can go stale unless reset or revalidated on vault changes, disconnect, and demo/live transitions.
* Error rendering can leak private filesystem detail unless output stays bounded and sanitized.

***

## 9. Testing Strategy

### Unit Tests

* Extend `src/components/hermes/__tests__/hermes-sections.test.tsx` with Memory layer rendering, section splitting, SOUL rendering, conversation callout, profile grid, and mode-state assertions.
* Extend the same test file with Obsidian bridge disabled, confirmation, pending, success, error, disconnect, and vault-path reset assertions.
* Extend `src/hooks/__tests__/use-hermes-admin.test.tsx` only if current coverage misses Obsidian duplicate-trigger prevention or confirmation payload behavior.

### Integration Tests

* Run focused Vitest coverage for Hermes section components, `useHermes`, `useHermesAdmin`, Hermes admin types, and existing bridge Obsidian tests.
* Use existing mocked fetch and mocked admin actions; do not require live Hermes, admin mode, or an Obsidian vault.

### Manual Testing

* Visit `/agents/hermes`, open the Memory tab in demo mode and live/setup-required modes.
* Verify memory success, empty, loading, error, offline, and token-failure states.
* Verify Obsidian admin-disabled, token-missing, confirmation-disabled, pending, success, and error states.
* Verify keyboard focus and labels for vault path input, confirmation, connect, disconnect, and profile grid controls.

### Edge Cases

* Empty USER or MEMORY content with existing file metadata.
* SOUL file is the default/template content and should not look like curated memory.
* Profiles endpoint succeeds with zero profiles while Memory succeeds.
* Sessions endpoint is empty or token-failed while Memory succeeds.
* Admin gate disabled after memory data loaded.
* Vault path changes after confirmation was checked.
* Obsidian mutation succeeds but returns a sanitized vault path, or fails with a path-like error string.

***

## 10. Dependencies

### External Libraries

* No new external libraries expected.

### Internal Dependencies

* `src/hooks/use-hermes.ts` for `memory`, `sessions`, and `profiles` views.
* `src/hooks/use-hermes-admin.ts` for `obsidian.connectVault`.
* `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts` for parser-backed contracts.
* `src/lib/hermes-demo-data.ts` for demo Memory/profile fixtures.
* `src/components/hermes/hermes-page-primitives.tsx` for visual/status primitives.
* `scripts/lib/hermes-admin-bridge.ts` and `scripts/lib/__tests__/hermes-admin-bridge.test.ts` for existing Obsidian safety proof.

### Other Sessions

* Depends on: `phase16-session01-guardrails-architecture-parity-baseline`, `phase16-session02-backend-endpoint-parity-write-safety`, `phase16-session03-data-layer-demo-fixtures`, `phase17-session01-visual-system-shell-status-pill`, `phase17-session02-chat-tab-write`, `phase17-session03-pantheon-upgrade-write`.
* Depended by: `phase18-session02-mnemosyne-constellation-readonly`, Phase 19 Hermes Orchestration And Documents, Phase 20 Hermes Long-Tail And Parity Sign-off.

***

## Next Steps

Run the `implement` workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase18-session01-memory-upgrade-write/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.