4.7 KiB

Raw Blame History

Setup Guide

Step-by-step installation of the Memory OS stack. Assumes Hermes Agent is already installed and configured.

Prerequisites

Hermes Agent 0.14.0+ (tested on 0.15.2)
Python 3.11+
Docker 24.0+
OpenRouter API key (for embeddings and LLM extraction)
16 GB RAM recommended (8 GB minimum)

Installation

1. Icarus Plugin (bundled)

# Copy the bundled Icarus fork into the Hermes plugins directory
cp -r icarus/ ~/.hermes/plugins/icarus/

2. Enable Icarus in Hermes Config

Icarus must be registered as an enabled plugin. Edit ~/.hermes/config.yaml:

enabled:
  - hermes-achievements       # optional
  - icarus                    # required — activates fabric tools + context injection hooks

Then restart the gateway:

hermes gateway restart

Verify the plugin loaded:

hermes status
# → Should show: icarus v0.3.0 (16 tools, 4 hooks)

3. Docker Infrastructure

# Copy docker-compose.yml from this repository
cp docker/docker-compose.yml ~/memory-os/
cd ~/memory-os

# Create .env with required variables
cat > .env << EOF
OPENROUTER_API_KEY=sk-or-...
REDIS_PASSWORD=$(openssl rand -hex 16)
EMBEDDING_DIMS=4096
COLLECTION_NAME=knowledge_base
EOF

docker compose up -d

Verify:

curl -s http://localhost:6333/healthz  # → {"title":"ok","version":"1.17.1"}
redis-cli -a "$REDIS_PASSWORD" ping    # → PONG

4. Environment Variables

Add to your Hermes profile .env (e.g. ~/.hermes/.env):

# Required
FABRIC_DIR=/home/your-user/vault/fabric
OPENROUTER_API_KEY=sk-or-...

# Strongly recommended
ICARUS_EXTRACTION_MAX_TOKENS=4096
ICARUS_EXTRACTION_MODEL=deepseek/deepseek-v4-flash
EMBEDDING_DIMS=4096

# Optional
ICARUS_OBSIDIAN=1
ICARUS_RESULT_MAX_CHARS=500
ICARUS_TASK_MAX_CHARS=300

⚠️ Use absolute paths. The Hermes gateway runs as a systemd service — ~ is not expanded. Always use /home/your-user/....

5. Core File Modifications

Apply the changes documented in modifications/soul-rulebook.md:

Add Ground Truth level 2 (injected memory) to SOUL.md
Add memory architecture documentation to rulebook.md
Add context injection convention to SOUL.md

These modifications ensure the agent trusts its injected memory as authoritative.

6. Wiki Setup

mkdir -p $VAULT_PATH/wiki/{raw,concepts,entities,comparisons,_meta,_archive}
# Copy SCHEMA.md template, create initial index.md and log.md

The wiki starts empty. Add source documents to raw/ and the wiki-agent cronjob will begin extracting structured pages.

7. Cronjobs

Add to crontab (crontab -e):

# Wiki ingestion — keeps Qdrant in sync
0 * * * *   /usr/bin/python3 /path/to/scripts/wiki_continuous_ingest.py

# Qdrant maintenance
0 3 * * 0   /usr/bin/python3 /path/to/scripts/decay_scanner.py

# Dead letter queue monitoring
0 */6 * * * /usr/bin/python3 /path/to/scripts/dlq_manager.py

# Semantic dedup (first Sunday of month)
0 3 * * 0   [ $(date +\%d) -le 7 ] && /usr/bin/python3 /path/to/scripts/semantic_dedup.py

8. Gateway Restart

hermes gateway restart

Changes to .env, SOUL.md, rulebook.md, and Icarus plugin code only take effect after restart.

9. Verify

Inside Hermes chat:

/plugins
# → Should show: icarus v0.3.0 (16 tools, 4 hooks)

fabric_brief()
# → Should show recent fabric entries (initially empty)

qdrant_search("test query")
# → Should return results from knowledge_base (if wiki has content)

fact_store(action='probe', entity='test')
# → Should return empty (no facts stored yet)

What to expect

Day 1: Infrastructure running. Fabric entries begin accumulating at session end. Qdrant indexing starts as wiki files are added.

Week 1: Context injection active. Agent references past decisions automatically. Wiki pipeline producing curated pages from raw documents.

Month 1: Decay scanner has aged content to evaluate. Structured facts accumulating with trust scores.

Troubleshooting

Qdrant collection shows 0 points

Check: EMBEDDING_DIMS=4096 matches collection schema. Mismatch → vectors rejected silently.

Fabric entries are truncated

Check: ICARUS_EXTRACTION_MAX_TOKENS=4096 in .env AND gateway was restarted after setting it.

Memory tool reports "Icarus write conflict"

Icarus is writing to MEMORY.md instead of CREATIVE.md. Verify Icarus fork is installed (not upstream esaradev version).

Context injection not working

Check: OpenRouter API key is set, context_enhancer.py can import, gateway restarted after hooks.py edits.

Decay scanner produces "0 archived" every week

Most likely: point payloads missing last_accessed_at or importance_score metadata. Run backfill before enabling decay.

4.7 KiB Raw Blame History