# Hermes Agent: Memory System Deep Dive

## Built-in Memory

### MEMORY.md (Agent's Notes)
- Capacity: 2,200 chars (~800 tokens)
- Stores: environment facts, project conventions, lessons learned, completed work
- Format: frozen snapshot at session start in system prompt
- Tool: `memory` with actions add/replace/remove
- Auto-saves: agent proactively saves facts it discovers
- Compaction: when full, agent consolidates or removes entries

### USER.md (User Profile)
- Capacity: 1,375 chars (~500 tokens)
- Stores: preferences, communication style, expectations
- Write gating: `memory.write_approval: true` requires approval before saves

### Session Search
- FTS5 full-text search on all past conversations
- Unlimited storage (all sessions in SQLite)
- `session_search` tool for the agent; `hermes sessions list` for the user
- ~20ms queries, no LLM call cost for search

## External Memory Providers (8 total)

| Provider | Storage | Cost | Tools | Best For |
|----------|---------|------|-------|----------|
| **Honcho** | Cloud | Paid | 5 | Multi-agent, cross-session user modeling |
| **OpenViking** | Self-hosted | Free | 5 | Structured knowledge hierarchy |
| **Mem0** | Cloud | Paid | 3 | Hands-off auto extraction |
| **Hindsight** | Cloud/Local | Free/Paid | 3 | Knowledge graph + entity relationships |
| **Holographic** | Local SQLite | Free | 2 | No external deps, trust scoring |
| **RetainDB** | Cloud | $20/mo | 5 | Teams using RetainDB |
| **ByteRover** | Local/Cloud | Free/Paid | 3 | Portable CLI-based memory |
| **Supermemory** | Cloud | Paid | 4 | Semantic recall + session graph |

## Recommended for ngn-agent

**Phase 2 start:** Built-in memory only — sufficient for ~15 env facts + ~10 user preferences.

**If more capacity needed:** Holographic (local SQLite + FTS5, zero external deps) or Honcho (cross-session user modeling with dialectic reasoning, good for platform engineering context that spans multiple projects).

## Key Settings

```yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  write_approval: false     # true to require approval before saves
  nudge_interval: 10        # turns between save nudges
  flush_min_turns: 6        # save memories on exit/reset after N turns
```

## What the Agent Auto-Saves

The agent proactively saves:
- User preferences ("prefers TypeScript" → USER.md)
- Environment facts ("this server runs Debian 12" → MEMORY.md)
- Corrections ("don't use sudo for Docker" → MEMORY.md)
- Conventions ("project uses tabs" → MEMORY.md)
- Completed work ("migrated DB from MySQL to PG" → MEMORY.md)

## What It Skips

- Trivial/obvious info
- Easily web-searchable facts
- Raw data dumps
- Session-specific ephemera
- Info already in context files

## Memory Write Approval Flow

```yaml
# When write_approval: true:
# CLI: prompts inline
# Gateway: stages for /memory pending → /memory approve <id>
```

Toggle at runtime: `/memory approval on|off`