bapung/ngn-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
07e09bc39732c167dfcfee88b7e5778775fa144c
ngn-agent/.planning/phases/05-hindsight-memory-provider/05-01-PLAN.md

375 lines
20 KiB
Markdown
Raw Blame History

---
phase: 05-hindsight-memory-provider
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- ~/.hermes/hindsight/config.json
- ~/.hermes/.env
- ~/.hermes/config.yaml
autonomous: true
requirements:
- MEM-01
user_setup: []
must_haves:
truths:
- "`hermes config get memory.provider` returns `hindsight`"
- "`~/.hermes/hindsight/config.json` exists with all locked config keys from D-04 through D-10"
- "`grep HINDSIGHT_LLM_API_KEY ~/.hermes/.env` returns the env var with the same value as OPENROUTER_API_KEY"
- "Hindsight daemon starts on first session init (verifiable via `~/.hermes/logs/hindsight-embed.log`)"
- "Agent has all 3 hindsight tools available (hindsight_retain, hindsight_recall, hindsight_reflect) in hybrid mode"
artifacts:
- path: "~/.hermes/hindsight/config.json"
provides: "Hindsight memory provider configuration with latency-optimized settings"
contains: "mode: local_embedded, recall_budget: low, retain_every_n_turns: 5, retain_async: true, memory_mode: hybrid"
- path: "~/.hermes/.env"
provides: "HINDSIGHT_LLM_API_KEY env var for daemon LLM extraction"
contains: "HINDSIGHT_LLM_API_KEY=sk-or-v1-"
- path: "~/.hermes/config.yaml"
provides: "memory.provider set to hindsight"
key_links:
- from: "~/.hermes/hindsight/config.json"
to: "~/.hermes/.env"
via: "HINDSIGHT_LLM_API_KEY env var in daemon startup"
pattern: "HINDSIGHT_LLM_API_KEY"
- from: "~/.hermes/config.yaml"
to: "plugins/memory/hindsight/__init__.py"
via: "memory.provider: hindsight activates HindsightMemoryProvider"
pattern: "memory.provider.*hindsight"
---
<objective>
Activate Hindsight as the cross-session memory provider for ngn-agent in local embedded mode with latency-optimized settings.
**Purpose:** Replace the limited built-in MEMORY.md/USER.md (2.2k chars, frozen per-session) with Hindsight's entity-aware knowledge graph memory for persistent cross-session recall. Pure configuration change — no code, no infrastructure, no Docker image changes.
**Output:**
- `~/.hermes/hindsight/config.json` — Hindsight config with all latency-optimized settings per D-01 through D-10
- `~/.hermes/.env` — `HINDSIGHT_LLM_API_KEY` env var appended (reuses existing OpenRouter key)
- `~/.hermes/config.yaml` — `memory.provider` changed to `hindsight`
</objective>
<execution_context>
@/Users/bapung/.config/opencode/gsd-core/workflows/execute-plan.md
@/Users/bapung/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@/Users/bapung/Razer/ngn-agent/.planning/phases/05-hindsight-memory-provider/05-CONTEXT.md
@/Users/bapung/Razer/ngn-agent/.planning/phases/05-hindsight-memory-provider/05-RESEARCH.md
# Existing state to read before modifying
@/Users/bapung/.hermes/config.yaml
@/Users/bapung/.hermes/.env
@/Users/bapung/.hermes/hermes-agent/plugins/memory/hindsight/README.md
# Critical constraint — single provider only
@/Users/bapung/.hermes/hermes-agent/plugins/memory/__init__.py
</context>
<tasks>
<task type="auto">
<name>Task 1: Create Hindsight config.json and add HINDSIGHT_LLM_API_KEY to .env</name>
<files>
~/.hermes/hindsight/config.json (create)
~/.hermes/.env (append)
</files>
<read_first>
@/Users/bapung/.hermes/hermes-agent/plugins/memory/hindsight/README.md (source of truth for all config keys)
@/Users/bapung/.hermes/.env (current state — must read before appending)
@/Users/bapung/Razer/ngn-agent/.planning/phases/05-hindsight-memory-provider/05-CONTEXT.md (verify locked decisions D-01 through D-10)
@/Users/bapung/Razer/ngn-agent/.planning/phases/05-hindsight-memory-provider/05-RESEARCH.md (verify exact config values)
</read_first>
<action>
Create `~/.hermes/hindsight/config.json` with the following EXACT content (per decisions D-01 through D-10):
```json
{
"mode": "local_embedded",
"llm_provider": "openrouter",
"llm_base_url": "https://openrouter.ai/api/v1",
"llm_model": "qwen/qwen3.5-9b",
"bank_id": "hermes",
"recall_budget": "low",
"recall_prefetch_method": "recall",
"auto_recall": true,
"recall_types": "observation",
"auto_retain": true,
"retain_async": true,
"retain_every_n_turns": 5,
"memory_mode": "hybrid"
}
```
Step-by-step:
1. Read `~/.hermes/.env` to get the current `OPENROUTER_API_KEY` value: `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`
2. Create directory: `mkdir -p ~/.hermes/hindsight`
3. Write the config.json above using Write tool (not heredoc)
4. Append `HINDSIGHT_LLM_API_KEY=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` to `~/.hermes/.env` ONLY if it doesn't already exist (grep first). Add a comment line above it: `# Hindsight — LLM API key for local embedded mode (reuses OpenRouter key)`
Key configuration rationale:
- `mode: local_embedded` (D-01): Local PostgreSQL daemon managed by Hermes. No external data send.
- `llm_provider: openrouter` (D-01): Use existing OpenRouter key. The `llm_base_url` matches OpenRouter's OpenAI-compatible endpoint.
- `llm_model: qwen/qwen3.5-9b` (D-01): Model per-provider default from plugin.
- `bank_id: hermes` (discretion): Default bank name from plugin.
- `recall_budget: low` (D-04): Fastest retrieval, minimal latency overhead per turn.
- `recall_prefetch_method: recall` (D-05): Raw fact search — no LLM synthesis in the hot path.
- `auto_recall: true` (D-06): Auto-inject context before each turn.
- `recall_types: observation` (D-07): Observations only, denser per token.
- `auto_retain: true` (D-10): Automatic retention active.
- `retain_async: true` (D-08): Processing in background, never blocks agent loop.
- `retain_every_n_turns: 5` (D-09): Extract memories every 5 turns (~80% overhead reduction).
- `memory_mode: hybrid` (D-02): Auto-inject relevant memories + expose all 3 hindsight tools (hindsight_retain, hindsight_recall, hindsight_reflect).
- No `bank_mission` or `bank_retain_mission` (discretion): Keep defaults (none).
- Do NOT set `api_url` (not needed for local_embedded mode — plugin defaults to localhost:9177).
- Do NOT set `HINDSIGHT_API_KEY` (not needed for local_embedded — that's for cloud mode).
</action>
<verify>
<automated>
test -f ~/.hermes/hindsight/config.json && echo "config.json EXISTS" || echo "config.json MISSING"
# Validate JSON syntax
python3 -c "import json; json.load(open('$HOME/.hermes/hindsight/config.json')); print('JSON VALID')"
# Verify all locked keys are present
python3 -c "
import json
c = json.load(open('$HOME/.hermes/hindsight/config.json'))
checks = {
'mode': c.get('mode') == 'local_embedded',
'llm_provider': c.get('llm_provider') == 'openrouter',
'llm_base_url': c.get('llm_base_url') == 'https://openrouter.ai/api/v1',
'llm_model': c.get('llm_model') == 'qwen/qwen3.5-9b',
'bank_id': c.get('bank_id') == 'hermes',
'recall_budget': c.get('recall_budget') == 'low',
'recall_prefetch_method': c.get('recall_prefetch_method') == 'recall',
'auto_recall': c.get('auto_recall') == True,
'recall_types': c.get('recall_types') == 'observation',
'auto_retain': c.get('auto_retain') == True,
'retain_async': c.get('retain_async') == True,
'retain_every_n_turns': c.get('retain_every_n_turns') == 5,
'memory_mode': c.get('memory_mode') == 'hybrid',
}
all_ok = all(checks.values())
for k, v in checks.items():
status = 'OK' if v else 'FAIL'
print(f' [{status}] {k}: {c.get(k)}')
assert all_ok, 'Config validation FAILED'
print('ALL CHECKS PASSED')
"
# Verify HINDSIGHT_LLM_API_KEY exists in .env and matches OPENROUTER_API_KEY
OR_KEY=$(grep '^OPENROUTER_API_KEY=' ~/.hermes/.env | cut -d= -f2-)
HL_KEY=$(grep '^HINDSIGHT_LLM_API_KEY=' ~/.hermes/.env | cut -d= -f2-)
if [ "$OR_KEY" = "$HL_KEY" ]; then echo "ENV KEY MATCH: $OR_KEY"; else echo "ENV KEY MISMATCH"; fi
</automated>
</verify>
<acceptance_criteria>
- `~/.hermes/hindsight/config.json` exists and is valid JSON
- All 13 config keys from D-01 through D-10 are present with correct values as verified by the python validation script
- `HINDSIGHT_LLM_API_KEY=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` is in `~/.hermes/.env`
- `HINDSIGHT_LLM_API_KEY` value is identical to `OPENROUTER_API_KEY` value
</acceptance_criteria>
<done>Hindsight config.json created with all 13 locked settings, env var added matching existing OpenRouter key</done>
</task>
<task type="auto">
<name>Task 2: Set memory.provider to hindsight, restart gateway, and verify full memory provider activation</name>
<files>
~/.hermes/config.yaml (modified via `hermes config set`)
</files>
<read_first>
@/Users/bapung/.hermes/hermes-agent/plugins/memory/__init__.py (read the single-provider constraint to understand the activation path)
@/Users/bapung/.hermes/config.yaml (read current memory.provider value — should be empty string before change)
</read_first>
<action>
Perform the following STEPS IN ORDER:
STEP 1 — Set memory provider:
Run: `hermes config set memory.provider hindsight`
This modifies `~/.hermes/config.yaml` setting `memory.provider: hindsight`.
NOTE: The current value at line 355 is `provider: ''` (empty string), meaning no external provider is set. After this command, it becomes `provider: hindsight`. The existing `memory.memory_enabled: true` and `memory.user_profile_enabled: true` remain unchanged — built-in memory continues as fallback (per D-03).
STEP 2 — Restart gateway:
Run: `hermes gateway restart`
This reloads config.yaml and activates the Hindsight provider. The plugin will:
- Detect `hindsight-all` is already installed in the venv (verified: 0.8.2)
- Read `~/.hermes/hindsight/config.json`
- Check existing `~/.hindsight/profiles/hermes.env` (already exists from previous attempt)
- Regenerate the profile env if it doesn't match config.json settings (per plugin __init__.py initialize() logic — Pitfall 5 prevention)
- The daemon will NOT start until the first session access (lazy init, not gateway restart)
STEP 3 — Verify provider is active:
Run: `hermes config get memory.provider`
Expected output: `hindsight`
Run: `hermes memory status`
Expected: Shows hindsight as the active memory provider. Output may say "not available" or similar for daemon status since daemon only starts on first session access (this is expected behavior — the provider IS registered, just the daemon hasn't been launched yet).
STEP 4 — Verify no provider conflict:
Run: `grep -i "Rejected memory provider" ~/.hermes/hermes-agent/logs/* 2>/dev/null || echo "No provider conflicts detected"`
Expected: No output (no rejections) since only one provider is set.
STEP 5 — Verify daemon readiness (check daemon binary exists in venv):
Run: `~/.hermes/hermes-agent/venv/bin/hindsight-embed --version 2>&1 || echo "(version flag not supported — this is fine)"`
Expected: Binary exists (no "not found" error).
STEP 6 — Final verification that all components are in place:
Run a comprehensive check combining config file, env var, and provider setting:
```
echo "=== Hindsight Phase 5 Verification ==="
echo "1. Config file: $(test -f ~/.hermes/hindsight/config.json && echo 'EXISTS' || echo 'MISSING')"
echo "2. Provider setting: $(hermes config get memory.provider)"
echo "3. Env var: $(grep -c '^HINDSIGHT_LLM_API_KEY=' ~/.hermes/.env | xargs -I{} echo 'FOUND ({})' )"
echo "4. Package: $(uv pip show hindsight-all --python ~/.hermes/hermes-agent/venv/bin/python 2>/dev/null | grep Version || echo 'NOT FOUND')"
echo "5. Daemon binary: $(ls ~/.hermes/hermes-agent/venv/bin/hindsight-embed 2>/dev/null && echo 'EXISTS' || echo 'NOT FOUND')"
echo "6. Daemon profile: $(ls ~/.hindsight/profiles/hermes.env 2>/dev/null && echo 'EXISTS' || echo 'NOT FOUND')"
echo "================================"
```
</action>
<verify>
<automated>
# Check provider is set correctly
[ "$(hermes config get memory.provider)" = "hindsight" ] && echo "Provider OK" || echo "Provider FAIL"
# Check no provider conflict in logs
LOG_DIR=~/.hermes/hermes-agent/logs
if [ -d "$LOG_DIR" ]; then
CONFLICT_COUNT=$(grep -c "Rejected memory provider" "$LOG_DIR"/*.log 2>/dev/null || echo 0)
if [ "$CONFLICT_COUNT" = "0" ]; then
echo "No provider conflict detected"
else
echo "WARNING: $CONFLICT_COUNT provider conflict(s) found"
fi
else
echo "No logs yet (no sessions started) — expected at this stage"
fi
# Full config validation using hermes config get (reads live config)
hermes config get memory.provider | grep -q hindsight || echo "CONFIG MISMATCH"
</automated>
</verify>
<acceptance_criteria>
- `hermes config get memory.provider` returns `hindsight`
- No "Rejected memory provider" warnings in logs (run `grep` check)
- `hindsight-embed` binary is present in the Hermes venv at `~/.hermes/hermes-agent/venv/bin/hindsight-embed`
- `hermes memory status` runs without errors and shows hindsight as the registered provider
</acceptance_criteria>
<done>Hindsight memory provider is set as the active external provider, gateway restarted, all verifications pass</done>
</task>
</tasks>
## Artifacts This Phase Produces
### New files
| Artifact | Path | Purpose |
|----------|------|---------|
| Hindsight config | `~/.hermes/hindsight/config.json` | All Hindsight configuration keys per D-01 through D-10 |
### Modified files
| Artifact | Path | Change |
|----------|------|--------|
| Env file | `~/.hermes/.env` | Added `HINDSIGHT_LLM_API_KEY` env var (same value as `OPENROUTER_API_KEY`) |
| Hermes config | `~/.hermes/config.yaml` | Changed `memory.provider` from `""` to `hindsight` |
### New env vars
| Env Var | Value | Source |
|---------|-------|--------|
| `HINDSIGHT_LLM_API_KEY` | `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` | Same as existing `OPENROUTER_API_KEY` in `~/.hermes/.env` |
### New config keys in `~/.hermes/config.yaml`
| Config Key | Value | Description |
|------------|-------|-------------|
| `memory.provider` | `hindsight` | Enables Hindsight as the active external memory provider |
### New config keys in `~/.hermes/hindsight/config.json`
| Key | Value | Decision |
|-----|-------|----------|
| `mode` | `local_embedded` | D-01 |
| `llm_provider` | `openrouter` | D-01 |
| `llm_base_url` | `https://openrouter.ai/api/v1` | D-01 |
| `llm_model` | `qwen/qwen3.5-9b` | D-01 |
| `bank_id` | `hermes` | Discretion |
| `recall_budget` | `low` | D-04 |
| `recall_prefetch_method` | `recall` | D-05 |
| `auto_recall` | `true` | D-06 |
| `recall_types` | `observation` | D-07 |
| `auto_retain` | `true` | D-10 |
| `retain_async` | `true` | D-08 |
| `retain_every_n_turns` | `5` | D-09 |
| `memory_mode` | `hybrid` | D-02 |
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| Agent process ↔ OpenRouter API | LLM extraction calls (memory entity extraction) cross the process-to-internet boundary with conversation turn data |
| Agent process ↔ Local PostgreSQL (daemon) | Memory data persisted in local embedded PostgreSQL via localhost:9177 — no network boundary |
| Agent loop ↔ Hindsight provider | Plugin hooks (queue_prefetch, sync_turn) operate in-process with background threads |
## STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-05-01 | Information Disclosure | OpenRouter API key reused as HINDSIGHT_LLM_API_KEY | mitigate | Key already stored in `~/.hermes/.env` with 0600 permissions (existing protection). Same key reused — no new secret to manage. Key is not logged beyond daemon startup. |
| T-05-02 | Denial of Service | Daemon startup failure / PostgreSQL embedded crash | mitigate | Daemon failure is non-fatal — agent continues with built-in memory fallback (D-03). Verify daemon log post-session-start. If daemon fails, memories are silently lost (async retain) but agent loop is unaffected. |
| T-05-03 | Elevation of Privilege | Daemon port localhost:9177 | mitigate | Daemon binds to localhost only (default). Not exposed to Docker container or network. Confirmed via README — no `HINDSIGHT_API_HOST` set means `0.0.0.0` is default but only reachable from host. |
| T-05-04 | Information Disclosure | Conversation data sent to OpenRouter for LLM extraction | accept | Local embedded mode means NO external data send to Hindsight Cloud. LLM extraction calls to OpenRouter carry only the conversation turn (~70-200 chars), not full history. This is the same OpenRouter endpoint already used for primary LLM calls. Equivalent risk to existing model calls. |
| T-05-05 | Tampering | Async retain silent failure | accept | Async retain failures are logged as warnings. Mitigation is monitoring (`grep "Hindsight retain failed"`). Not blocking the agent loop is intentional per D-08. |
| T-05-SC | Tampering | Python package installations (`hindsight-all`, `hindsight-client`, `hindsight-embed`, `hindsight-api-slim`) | mitigate | Package legitimacy verified in RESEARCH.md §Package Legitimacy Audit — all packages from Vectorize.io (same org as Hermes plugin). Already installed at version 0.8.2. No new install needed. |
### Residual Risk
| Risk | Why Accepted |
|------|--------------|
| LLM extraction timeout or error causes memory loss for that turn | Async retain swallows failures; memories from that turn are lost. Mitigated by `retain_every_n_turns: 5` — next retain window will capture subsequent turns. |
| OpenRouter rate limiting on extraction calls | Same key used for model calls and extraction; extraction happens every 5 turns (~70-200 chars), which is negligible compared to model call traffic. |
</threat_model>
<verification>
Run after all tasks complete:
```bash
echo "=== Phase 5 Full Verification ==="
echo "--- Step 1: Provider Check ---"
hermes config get memory.provider
echo "--- Step 2: Config File ---"
python3 -c "import json; c=json.load(open('$HOME/.hermes/hindsight/config.json')); print('mode:', c['mode']); print('budget:', c['recall_budget']); print('async retain:', c['retain_async']); print('every_n:', c['retain_every_n_turns']); print('memory_mode:', c['memory_mode'])"
echo "--- Step 3: Env Var ---"
grep '^HINDSIGHT_LLM_API_KEY=' ~/.hermes/.env | grep -o '^HINDSIGHT_LLM_API_KEY=sk-or-v1-' && echo "Format OK"
echo "--- Step 4: Package ---"
uv pip show hindsight-all --python ~/.hermes/hermes-agent/venv/bin/python 2>/dev/null | grep -E '(Name|Version)'
echo "--- Step 5: Daemon Binary ---"
ls -la ~/.hermes/hermes-agent/venv/bin/hindsight-embed 2>/dev/null
echo "--- Step 6: Daemon Profile (pre-existing) ---"
ls -la ~/.hindsight/profiles/hermes.env 2>/dev/null
echo "--- Step 7: Provider Conflict Check ---"
grep -i "Rejected memory provider" ~/.hermes/hermes-agent/logs/*.log 2>/dev/null || echo "No conflicts"
echo "=== Verification Complete ==="
```
</verification>
<success_criteria>
1. `hermes config get memory.provider` returns `hindsight` — provider activated
2. `~/.hermes/hindsight/config.json` exists with valid JSON containing all 13 locked settings — config complete
3. `grep HINDSIGHT_LLM_API_KEY ~/.hermes/.env` returns the env var matching OPENROUTER_API_KEY — LLM extraction configured
4. `~/.hermes/hermes-agent/venv/bin/hindsight-embed` binary exists — daemon ready for first session start
5. No "Rejected memory provider" warnings in gateway logs — no provider conflict
6. Built-in MEMORY.md/USER.md continues working in parallel (no config changes to memory_enabled/user_profile_enabled) — fallback preserved per D-03
</success_criteria>
<output>
Create `.planning/phases/05-hindsight-memory-provider/05-01-SUMMARY.md` when done
</output>
Reference in New Issue View Git Blame Copy Permalink