Notion-backed persistent long-term memory for the Hermes AI agent ecosystem. Organizes decisions, tasks, projects, research, and custom domains across structured Notion databases.

hermes-brain replaces local flat markdown memory files (MEMORY.md / USER.md) with a structured, multi-database Notion workspace under a single Hermes Brain parent page.

Instead of an agent forgetting decisions or cluttering a single text file across long sessions, context is classified into dedicated databases with typed properties, status tracking, confidence scoring, and tag indexing.

Conversation Turn (User / Assistant)
       │
       ├──────────────────────────────────────────────┐
[Synchronous Execution]                        [Asynchronous Background Worker]
       │                                              │
1. prefetch()                                  1. sync_turn()
   - Injects relevant memory context              - Pushes turn to daemon queue
2. Tool Calls                                  2. extract.classify_turn()
   - notion_brain_search                          - Regex heuristics / optional local LLM
   - notion_brain_remember                     3. BrainEntry.normalized()
   - notion_brain_task                            - Secret redaction (sk-, ntn-, ghp-, keys)
   - notion_brain_content                      4. store.create_database_page()
   - notion_brain_research                        - Writes to Notion API (1900-char blocks)

• Python 3.11 to 3.13
• Notion integration token (create one at notion.so/my-integrations)
• Hermes Agent

Install into the Hermes Agent virtual environment:

~/.hermes/hermes-agent/venv/bin/pip install -e /path/to/hermes-brain

Or symlink into your Hermes user plugins directory:

mkdir -p ~/.hermes/plugins
ln -s /path/to/hermes-brain/notion_brain ~/.hermes/plugins/notion_brain

Symlink the companion skill so Hermes knows when to trigger explicit memory actions:

mkdir -p ~/.hermes/skills
ln -s /path/to/hermes-brain/skills/notion-brain ~/.hermes/skills/notion-brain

Add your Notion integration token to ~/.hermes/.env:

echo "NOTION_API_KEY=ntn_your_notion_token_here" >> ~/.hermes/.env
chmod 600 ~/.hermes/.env

Run the setup wizard to choose your workspace structure:

hermes-brain setup

The wizard prompts you for:

1. Standard databases to create: Select from the 7 starter templates (Memory, Tasks, Projects, Content, Research, Career, Entities).
2. Custom databases: Add application-specific databases (e.g. fitness, finance) with custom typed fields (Reps:number, Exercise:select).
3. Workspace bootstrap: Creates the Hermes Brain parent page and builds the chosen databases in Notion.

Important: Open your Hermes Brain page in Notion and share it with your integration (••• -> Connections -> add your integration).

Run the standalone verification script without launching Hermes:

python examples/quickstart.py

In ~/.hermes/config.yaml:

memory:
  memory_enabled: true
  provider: notion_brain

Ensure memory is removed from disabled_toolsets if present.

You can configure custom databases during interactive setup or via command-line flags for automation:

hermes-brain setup --standard-dbs 1,2,3 --custom-json '[{"key":"fitness","title":"Workouts","fields":{"Reps":"number","Exercise":"select"}}]' --non-interactive

Custom databases automatically inherit the base audit properties (Title, Domain, Status, Tags, Confidence, Source Session, Last Seen) in addition to your custom fields.

• Non-Blocking Background Worker: Writes are pushed to an in-memory queue and processed by a dedicated daemon thread. Notion API latency never delays conversation turns.
• Prompt-Cache Integrity: Base system prompt text remains static across sessions. Dynamic memories are injected via prefetch() and tool responses, preventing prompt-cache invalidation.
• Strict Secret Redaction: All text passes through redact_secrets() before leaving the machine. OpenAI (sk-), Notion (ntn_), GitHub (ghp_), Slack (xoxb-), AWS tokens, and private keys are scrubbed.
• Safe Exception Boundaries: Exceptions raised during API calls suppress raw stack traces (raise ... from None) to prevent unredacted tokens from leaking into error logs.
• Page Deduplication: Title checks verify existing entries before writing, executing a PATCH update rather than creating duplicate pages.
• Full Block Body Hydration: Recursive cursor pagination retrieves full multi-paragraph page bodies from /blocks/{id}/children, bypassing the 200-character property truncation limit.
• Block Chunking: Long content is automatically divided into 1900-character paragraph blocks to respect Notion's 2000-character block boundary.

When active, Hermes has access to 5 dedicated tools:

• notion_brain_search: Search across all databases or filter by a specific database (memory, tasks, projects, content, research, career, entities, or custom keys).
• notion_brain_remember: Save explicit notes, decisions, or facts when heuristic capture does not apply.
• notion_brain_task: Manage tasks (create, list, update, complete).
• notion_brain_content: Manage social media drafts and post ideas by platform and publishing status.
• notion_brain_research: Log and list research citations, summaries, and findings.

The hermes-brain CLI provides maintenance utilities:

hermes-brain setup     # Run interactive database onboarding wizard
hermes-brain health    # Check database status, schema matches, and row counts
hermes-brain url       # Print Notion URL for the parent page (use --all for databases)
hermes-brain reset     # Recreate databases with schema mismatches
hermes-brain wipe      # Clear rows from specified databases (use --dry-run to test)
hermes-brain import    # Import legacy local MEMORY.md and USER.md files into Notion
hermes-brain update    # Check for and install updates from GitHub

Run unit tests:

pytest

Run linter and type checks:

ruff check .
mypy notion_brain

For project documentation, policies, and guidelines, see:

• Architecture Details
• Troubleshooting Guide
• Contributing Guidelines
• Security Policy
• Code of Conduct
• Changelog

MIT License © MNDL-27

If you find this project useful, please consider starring it ⭐ or following for more AI infrastructure tools.

Built with ❤️ from