timmy-home/docs/MEMPALACE_EZRA_INTEGRATION.md

# MemPalace v3.0.0 — Ezra Integration Packet

This packet turns issue #570 into an executable, reviewable integration plan for Ezra's Hermes home.
It is a repo-side scaffold: no live Ezra host changes are claimed in this artifact.

## Commands

```bash
pip install mempalace==3.0.0
mempalace init ~/.hermes/ --yes
cat > ~/.hermes/mempalace.yaml <<'YAML'
wing: ezra_home
palace: ~/.mempalace/palace
rooms:
  - name: sessions
    description: Conversation history and durable agent transcripts
    globs:
      - "*.json"
      - "*.jsonl"
  - name: config
    description: Hermes configuration and runtime settings
    globs:
      - "*.yaml"
      - "*.yml"
      - "*.toml"
  - name: docs
    description: Notes, markdown docs, and operating reports
    globs:
      - "*.md"
      - "*.txt"
people: []
projects: []
YAML
echo "" | mempalace mine ~/.hermes/
echo "" | mempalace mine ~/.hermes/sessions/ --mode convos
mempalace search "your common queries"
mempalace wake-up
hermes mcp add mempalace -- python -m mempalace.mcp_server
```

## Manual config template

```yaml
wing: ezra_home
palace: ~/.mempalace/palace
rooms:
  - name: sessions
    description: Conversation history and durable agent transcripts
    globs:
      - "*.json"
      - "*.jsonl"
  - name: config
    description: Hermes configuration and runtime settings
    globs:
      - "*.yaml"
      - "*.yml"
      - "*.toml"
  - name: docs
    description: Notes, markdown docs, and operating reports
    globs:
      - "*.md"
      - "*.txt"
people: []
projects: []
```

## Native MCP config snippet

```yaml
mcp_servers:
  mempalace:
    command: python
    args:
      - -m
      - mempalace.mcp_server
```

## Session start wake-up hook

Drop this into Ezra's session start wrapper (or source it before starting Hermes) so the wake-up context is refreshed automatically.

```bash
#!/usr/bin/env bash
set -euo pipefail

if command -v mempalace >/dev/null 2>&1; then
  mkdir -p "~/.hermes/wakeups"
  mempalace wake-up > "~/.hermes/wakeups/ezra_home.txt"
  export HERMES_MEMPALACE_WAKEUP_FILE="~/.hermes/wakeups/ezra_home.txt"
  printf '[MemPalace] wake-up context refreshed: %s\n' "$HERMES_MEMPALACE_WAKEUP_FILE"
fi
```

## Metrics reply for #568

Use this as the ready-to-fill comment body after the live Ezra run:

```md
# Metrics reply for #568

Refs #570.

## Ezra live run
- package: mempalace==3.0.0
- hermes home: ~/.hermes/
- sessions dir: ~/.hermes/sessions/
- palace path: ~/.mempalace/palace
- wake-up file: ~/.hermes/wakeups/ezra_home.txt

## Results to fill in
- install result: [pass/fail + note]
- init result: [pass/fail + note]
- mine home duration: [seconds]
- mine sessions duration: [seconds]
- corpus size after mining: [drawers/rooms]
- query 1: [query] -> [top result]
- query 2: [query] -> [top result]
- query 3: [query] -> [top result]
- wake-up context token count: [tokens]
- MCP wiring succeeded: [yes/no]
- session-start hook enabled: [yes/no]

## Commands actually used
```bash
pip install mempalace==3.0.0
mempalace init ~/.hermes/ --yes
echo "" | mempalace mine ~/.hermes/
echo "" | mempalace mine ~/.hermes/sessions/ --mode convos
mempalace search "your common queries"
mempalace wake-up
hermes mcp add mempalace -- python -m mempalace.mcp_server
```
```

## Operator-ready support bundle

Generate copy-ready files for Ezra's host with:

```bash
python3 scripts/mempalace_ezra_integration.py --bundle-dir /tmp/ezra-mempalace-bundle
```

That bundle writes:
- `mempalace.yaml`
- `hermes-mcp-mempalace.yaml`
- `session-start-mempalace.sh`
- `issue-568-comment-template.md`

## Why this shape

- `wing: ezra_home` matches the issue's Ezra-specific integration target.
- `rooms` split the mined material into sessions, config, and docs to keep retrieval interpretable.
- Mining commands pipe empty stdin to avoid the interactive entity-detector hang noted in the evaluation.
- `mcp_servers:` gives the native-MCP equivalent of `hermes mcp add ...`, so the operator can choose either path.
- `HERMES_MEMPALACE_WAKEUP_FILE` makes the wake-up context explicit and reusable from the session-start boundary.

## Gotchas

- `mempalace init` is still interactive in room approval flow; write mempalace.yaml manually if the init output stalls.
- The yaml key is `wing:` not `wings:`. Using the wrong key causes mine/setup failures.
- Pipe empty stdin into mining commands (`echo "" | ...`) to avoid the entity-detector stdin hang on larger directories.
- First mine downloads the ChromaDB embedding model cache (~79MB).
- Report Ezra's before/after metrics back to issue #568 after live installation and retrieval tests.

## Report back to #568

After live execution on Ezra's actual environment, post back to #568 with:
- install result
- mine duration and corpus size
- 2-3 real search queries + retrieved results
- wake-up context token count
- whether MCP wiring succeeded
- whether the session-start hook exported `HERMES_MEMPALACE_WAKEUP_FILE`

## Honest scope boundary

This repo artifact does **not** prove live installation on Ezra's host. It makes the work reproducible and testable so the next pass can execute it without guesswork.