178 lines
4.7 KiB
Markdown
178 lines
4.7 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```yaml
|
|
enabled:
|
|
- hermes-achievements # optional
|
|
- icarus # required — activates fabric tools + context injection hooks
|
|
```
|
|
|
|
Then restart the gateway:
|
|
|
|
```bash
|
|
hermes gateway restart
|
|
```
|
|
|
|
Verify the plugin loaded:
|
|
|
|
```bash
|
|
hermes status
|
|
# → Should show: icarus v0.3.0 (16 tools, 4 hooks)
|
|
```
|
|
|
|
### 3. Docker Infrastructure
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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`):
|
|
|
|
```bash
|
|
# 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](../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
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```cron
|
|
# 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
|
|
|
|
```bash
|
|
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.
|