Hermes Memory

Hermes Memory

Purpose

• Keep long-lived project facts out of ephemeral chat history.
• Load only the memory that matters for the current task.
• Save reusable lessons instead of repeating the same investigation later.
• Prevent memory sprawl by separating durable facts from temporary chatter.
• Make project knowledge auditable, editable, and diffable.

What Counts As Durable Memory

• architecture decisions
• naming conventions
• repository-specific workflows
• known failure signatures and fixes
• user preferences that change how work should be done
• stable environment constraints
• reusable commands or validation routines
• external integration quirks that repeatedly matter

What Does Not Belong In Memory

• one-off task status
• temporary branch names
• speculative ideas that were never adopted
• verbose transcripts
• sensitive secrets or tokens
• logs that can be regenerated
• transient failures without a confirmed lesson

Suggested Layout

• memory/MEMORY.md as the index
• one file per topic or subsystem
• stable headings inside each memory file
• short descriptions in the index so prefetch remains cheap

Canonical Headings

• ## Decisions
• ## Preferences
• ## Tooling Notes
• ## Error Patterns
• ## Validation
• ## Open Questions

Operations

Prefetch

• Use before nontrivial work.
• Read the memory index first.
• Select only files relevant to the current task.
• Summarize the relevant items into a short working context.
• Do not dump full memory files into the answer unless asked.

Sync

• Use after completing work with durable lessons.
• Review what changed in understanding, not just what files changed.
• Merge new facts into the most specific existing file.
• Create a new file only when no current topic fits cleanly.
• Update MEMORY.md if a new file is created.

Nudge

• Use after complex work when valuable lessons exist but should not be saved automatically.
• Produce candidates and proposed destinations.
• Ask for confirmation when the workflow or environment requires explicit approval.
• Prefer small curated memory candidates over bulk transcript dumps.

Compress

• Use when memory files become repetitive or bloated.
• Merge duplicate bullets.
• Promote stable headings.
• Remove stale or contradicted material.
• Replace long narratives with short factual bullets.

Status

• Use to audit coverage and hygiene.
• Check for missing files referenced by the index.
• Check for oversized files that need compression.
• Check for duplicate topics across files.

Prefetch Procedure

1. Read the index.
2. Match the current task to likely topics.
3. Open only the top few relevant files.
4. Extract facts that constrain the task.
5. Separate hard constraints from softer preferences.
6. Return a compact memory-context block.
7. List what files were checked and which were actually relevant.

Sync Procedure

1. Review the completed work.
2. Ask what lesson would help six weeks from now.
3. Reject task-local noise.
4. Map each accepted lesson to an existing topic file.
5. Add or edit concise bullets under stable headings.
6. Update the index if the topic is new.
7. Report what was saved and where.