d578d06f59
CRITICAL fixes: - Installation: Remove false prerequisites (installer auto-installs everything except git) - Tools: Remove non-existent 'web_crawl' tool from tools table - Memory: Remove non-existent 'read' action (only add/replace/remove exist) - Code execution: Fix 'search' to 'search_files' in sandbox tools list - CLI commands: Fix --model/--provider/--toolsets/--verbose as chat subcommand flags IMPORTANT fixes: - Installation: Add missing installer features (Node.js, ripgrep, ffmpeg, skills seeding) - Installation: Add 6 missing package extras to table (mcp, honcho, tts-premium, etc) - Installation: Fix mkdir to include all directories the installer creates - Quickstart: Add OpenAI Codex to provider table - CLI: Fix all 'hermes --flag' to 'hermes chat --flag' across all docs - Configuration: Remove non-existent --max-turns CLI flag - Tools: Fix 'search' to 'search_files', add missing 'process' tool - Skills: Remove skills_categories() (not a registered tool) - Cron: Remove unsupported 'daily at 9am' schedule format - TTS: Fix output directory to ~/.hermes/audio_cache/ - Delegation: Clarify depth limit wording - Architecture: Fix default model, chat() signature, file names - Contributing: Fix Python requirement from 3.11+ to 3.10+ - CLI reference: Add missing commands (login, tools, sessions subcommands) - Env vars: Fix TERMINAL_DOCKER_IMAGE default, add HERMES_MODEL
99 lines
3.3 KiB
Markdown
99 lines
3.3 KiB
Markdown
---
|
|
sidebar_position: 3
|
|
title: "Persistent Memory"
|
|
description: "How Hermes Agent remembers across sessions — MEMORY.md, USER.md, and session search"
|
|
---
|
|
|
|
# Persistent Memory
|
|
|
|
Hermes Agent has bounded, curated memory that persists across sessions. This lets it remember your preferences, your projects, your environment, and things it has learned.
|
|
|
|
## How It Works
|
|
|
|
Two files make up the agent's memory:
|
|
|
|
| File | Purpose | Token Budget |
|
|
|------|---------|-------------|
|
|
| **MEMORY.md** | Agent's personal notes — environment facts, conventions, things learned | ~800 tokens (~2200 chars) |
|
|
| **USER.md** | User profile — your preferences, communication style, expectations | ~500 tokens (~1375 chars) |
|
|
|
|
Both are stored in `~/.hermes/memories/` and are injected into the system prompt as a frozen snapshot at session start. The agent manages its own memory via the `memory` tool — it can add, replace, or remove entries.
|
|
|
|
:::info
|
|
Character limits keep memory focused. When memory is full, the agent consolidates or replaces entries to make room for new information.
|
|
:::
|
|
|
|
## Configuration
|
|
|
|
```yaml
|
|
# In ~/.hermes/config.yaml
|
|
memory:
|
|
memory_enabled: true
|
|
user_profile_enabled: true
|
|
memory_char_limit: 2200 # ~800 tokens
|
|
user_char_limit: 1375 # ~500 tokens
|
|
```
|
|
|
|
## Memory Tool Actions
|
|
|
|
The agent uses the `memory` tool with these actions:
|
|
|
|
- **add** — Add a new memory entry
|
|
- **replace** — Replace an existing entry with updated content
|
|
- **remove** — Remove an entry that's no longer relevant
|
|
|
|
Memory content is automatically injected into the system prompt at session start — there is no `read` action. The agent sees its memories as part of the conversation context.
|
|
|
|
## Session Search
|
|
|
|
Beyond MEMORY.md and USER.md, the agent can search its past conversations using the `session_search` tool:
|
|
|
|
- All CLI and messaging sessions are stored in SQLite (`~/.hermes/state.db`) with FTS5 full-text search
|
|
- Search queries return relevant past conversations with Gemini Flash summarization
|
|
- The agent can find things it discussed weeks ago, even if they're not in its active memory
|
|
|
|
```bash
|
|
hermes sessions list # Browse past sessions
|
|
```
|
|
|
|
## Honcho Integration (Cross-Session User Modeling)
|
|
|
|
For deeper, AI-generated user understanding that works across tools, you can optionally enable [Honcho](https://honcho.dev/) by Plastic Labs. Honcho runs alongside existing memory — USER.md stays as-is, and Honcho adds an additional layer of context.
|
|
|
|
When enabled:
|
|
- **Prefetch**: Each turn, Honcho's user representation is injected into the system prompt
|
|
- **Sync**: After each conversation, messages are synced to Honcho
|
|
- **Query tool**: The agent can actively query its understanding of you via `query_user_context`
|
|
|
|
**Setup:**
|
|
|
|
```bash
|
|
# 1. Install the optional dependency
|
|
uv pip install honcho-ai
|
|
|
|
# 2. Get an API key from https://app.honcho.dev
|
|
|
|
# 3. Create ~/.honcho/config.json
|
|
cat > ~/.honcho/config.json << 'EOF'
|
|
{
|
|
"enabled": true,
|
|
"apiKey": "your-honcho-api-key",
|
|
"peerName": "your-name",
|
|
"hosts": {
|
|
"hermes": {
|
|
"workspace": "hermes"
|
|
}
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
Or via environment variable:
|
|
```bash
|
|
hermes config set HONCHO_API_KEY your-key
|
|
```
|
|
|
|
:::tip
|
|
Honcho is fully opt-in — zero behavior change when disabled or unconfigured. All Honcho calls are non-fatal; if the service is unreachable, the agent continues normally.
|
|
:::
|