Tutorial: Your First Memory
Walk one fact from a chat session to approved agent memory, step by step.
In this tutorial you will follow a single fact through the whole pipeline: archive, stage, review, and remember. It takes about ten minutes and you need nothing beyond a working install.
01-Projects/ and _System/). Use python on Windows and python3 on Linux or macOS. If you have not installed yet, do the Quickstart first.What you will do
| Step | Stage | Where the fact lives afterwards |
|---|---|---|
| 1. Check the install | n/a | n/a |
| 2. Archive a session | Archive | 04-Archives/Daily/YYYY/MM/DD/ |
| 3. Stage candidates | Stage | 04-Archives/Memory-Review/ |
| 4. Review them | Review | MEMORY.md, 02-Areas/User-Profile.md, or dismissed |
| 5. Sync to Hermes | Remember | Hermes native memory |
1. Check the install
Run the MCP server’s self-test and list pending candidates. Neither needs Hermes to be running.
python _System/Scripts/hermes_brain_mcp.py --test
python _System/Scripts/promote_memory.py --list
The first command ends with All hermes-brain-mcp self-tests PASSED. The second prints [] on a fresh vault, meaning nothing is waiting for review yet.
If either fails, see Troubleshooting.
2. Archive a session
Have a short conversation with Hermes first, for example tell it “I prefer short answers with a concrete example.” Then export your recent sessions without waiting for the hourly job:
python3 _System/Scripts/archive_now.py
Open 04-Archives/Daily/ in Obsidian. You will find today’s session as a Markdown note, under YYYY/MM/DD/. Secrets such as API keys are scrubbed before the note is written, and a manifest.jsonl records the export so the same session is never archived twice.
manifest.jsonl can corrupt it.3. Stage candidate facts
Staging is a mechanical, LLM-free pass that pulls candidate facts out of your archived sessions:
python3 _System/Scripts/consolidate_memory.py
python _System/Scripts/promote_memory.py --list
Each candidate is a Markdown file in 04-Archives/Memory-Review/. The list command now shows them.
Your agent can also stage a fact itself, through the MCP server tool stage_memory_candidate. It lands in the same folder, so it goes through the same review.
4. Review the candidates
This is the step that keeps you in control. Walk through candidates one at a time:
python _System/Scripts/promote_memory.py --review
For each candidate you can promote it, dismiss it, or skip it for later. You can also act on one file directly:
# Promote to Hermes native memory
python _System/Scripts/promote_memory.py --file 04-Archives/Memory-Review/<candidate>.md --target hermes
# Promote to your user profile instead
python _System/Scripts/promote_memory.py --file 04-Archives/Memory-Review/<candidate>.md --target profile
# Reject it
python _System/Scripts/promote_memory.py --file 04-Archives/Memory-Review/<candidate>.md --target dismiss
Every action is written to an audit log, 04-Archives/Memory-Review/Consolidation-Log.md. Nothing is promoted automatically.
04-Archives/Memory-Review/Memory-Board.kanban) shows candidates as cards.5. Sync to Hermes
Promoted facts are copied into Hermes’s own memory files, which are injected into every turn. Preview first, then apply:
python _System/Scripts/sync_to_hermes.py --dry-run
python _System/Scripts/sync_to_hermes.py
Start a new Hermes chat and ask it something that depends on the fact you promoted. It now knows it across sessions, and only because you approved it.
What you just learned
- Sessions are archived as plain Markdown and scrubbed of secrets.
- Candidate facts wait in a review queue. Nothing becomes memory on its own.
- Every promote or dismiss is logged.
Next steps
- Read Architecture to see why each stage exists.
- Automate steps 2 and 3 with the prompts on the Install Prompts page.
- Browse the scripts reference for the other tools, such as the vault audit.