---
title: "Content Placeholder"
build:
  render: never
  list: never
  publishResources: false
draft: true
---

# 📚 Полная инструкция по установке Memory OS + Hermes Agent

## Содержание
1. [Подготовка окружения](#1-подготовка-окружения)
2. [Настройка хранилищ](#2-настройка-хранилищ)
3. [Установка Memory OS](#3-установка-memory-os)
4. [Решение проблем](#4-решение-проблем)
5. [Проверка работы](#5-проверка-работы)
6. [Настройка автоматизации](#6-настройка-автоматизации)

---

## 1. Подготовка окружения

### 1.1. Системные требования
- Ubuntu 22.04/24.04 (или аналогичный Linux)
- Python 3.11+
- Docker 24.0+ и Docker Compose
- 16 GB RAM (рекомендуется)

### 1.2. Установка Docker и Docker Compose

```bash
# Установка Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Установка Docker Compose
sudo apt install docker-compose-plugin
```

### 1.3. Установка Python и uv

```bash
# Установка Python
sudo apt install python3 python3-venv python3-pip

# Установка uv (быстрый менеджер пакетов)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
```

### 1.4. Установка Ollama (для локальных эмбеддингов)

```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text  # или другую модель
```

---

## 2. Настройка хранилищ

### 2.1. Создание структуры каталогов

```bash
# Основная директория для всех данных
sudo mkdir -p /opt/hermes
sudo chown $USER:$USER /opt/hermes

# Структура данных
mkdir -p /opt/hermes/.hermes
mkdir -p /opt/hermes/vault/{wiki,raw,concepts,entities,comparisons,_meta,_archive}
mkdir -p /opt/hermes/vault/fabric
mkdir -p /opt/hermes/.hermes/logs
mkdir -p /opt/hermes/.hermes/cron/output
```

### 2.2. Монтирование Obsidian Vault (опционально)

**Если у вас Obsidian Vault в S3:**

```bash
# Установка s3fs
sudo apt install s3fs -y

# Создание файла с ключами
echo "ACCESS_KEY:SECRET_KEY" > ~/.passwd-s3fs
chmod 600 ~/.passwd-s3fs

# Монтирование
s3fs obsidian /opt/hermes/obsidian-vault \
  -o passwd_file=/home/$USER/.passwd-s3fs \
  -o allow_other \
  -o use_cache=/tmp \
  -o url=https://s3.nixg.ru \
  -o endpoint=garage \
  -o use_path_request_style \
  -o sigv4

# Для автоматического монтирования (fstab)
echo "s3fs#obsidian /opt/hermes/obsidian-vault fuse _netdev,allow_other,passwd_file=/etc/passwd-s3fs,use_cache=/tmp,url=https://s3.nixg.ru,endpoint=garage,use_path_request_style,sigv4 0 0" | sudo tee -a /etc/fstab
```

### 2.3. Настройка переменных окружения

```bash
# Добавьте в ~/.bashrc
export HERMES_HOME=/opt/hermes/.hermes
export VAULT_PATH=/opt/hermes/vault
export WIKI_PATH=/opt/hermes/vault/wiki
export OBSIDIAN_VAULT_PATH=/opt/hermes/obsidian-vault
source ~/.bashrc
```

---

## 3. Установка Memory OS

### 3.1. Клонирование репозитория

```bash
cd /opt/hermes
git clone https://github.com/ClaudioDrews/memory-os.git
cd memory-os
```

### 3.2. Настройка виртуального окружения

```bash
# Через uv
uv venv --python 3.12
source .venv/bin/activate
uv pip install -r requirements.txt

# Или через venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 3.3. Настройка .env

```bash
cp .env.example .env
nano .env
```

**Пример `.env` для Polza.ai:**

```bash
# ── Required ──────────────────────────────────────────
REDIS_PASSWORD=26a7b9ccfc87717cf1e7b5e1ebf514a8

# ── Paths ─────────────────────────────────────────────
FABRIC_DIR=/opt/hermes/vault/fabric
VAULT_PATH=/opt/hermes/vault
WIKI_ROOT=/opt/hermes/vault/wiki
HERMES_HOME=/opt/hermes/.hermes
STATE_DB_PATH=/opt/hermes/.hermes/state.db
HERMES_LOGS_DIR=/opt/hermes/.hermes/logs

# ── Embedding Backend (Polza.ai) ─────────────────────
EMBEDDING_API_BASE=https://polza.ai/api/v1
EMBEDDING_MODEL=qwen/qwen3-embedding-8b
EMBEDDING_API_KEY=pza_ваш_ключ_здесь
EMBEDDING_DIMS=4096

# ── Icarus Extraction ─────────────────────────────────
ICARUS_ENDPOINT=https://polza.ai/api/v1/chat/completions
ICARUS_API_KEY_ENV=pza_ваш_ключ_здесь
ICARUS_EXTRACTION_MAX_TOKENS=4096
ICARUS_EXTRACTION_MODEL=qwen/qwen3-embedding-8b

# ── Strongly Recommended ──────────────────────────────
HERMES_AGENT_NAME=hermes
COLLECTION_NAME=knowledge_base

# ── Obsidian Integration ──────────────────────────────
ICARUS_OBSIDIAN=1
OBSIDIAN_VAULT_PATH=/opt/hermes/obsidian-vault

# ── Docker Compose volumes ────────────────────────────
MEMORY_OS_WIKI_PATH=/opt/hermes/vault/wiki
MEMORY_OS_HERMES_HOME=/opt/hermes/.hermes
MEMORY_OS_FABRIC_DIR=/opt/hermes/vault/fabric
```

### 3.4. Запуск Docker стека

```bash
cd /opt/hermes/memory-os/docker
cp ../.env .env
docker compose up -d
```

### 3.5. Установка плагина Icarus

```bash
cp -r /opt/hermes/memory-os/icarus /opt/hermes/.hermes/plugins/
```

### 3.6. Настройка контекстного усилителя

```bash
mkdir -p /opt/hermes/.hermes/scripts
ln -sf /opt/hermes/memory-os/scripts/context_enhancer.py /opt/hermes/.hermes/scripts/context_enhancer.py
```

### 3.7. Настройка базы данных

```bash
cd /opt/hermes/memory-os
python3 setup/setup_db.py
```

### 3.8. Применение протокола

```bash
if [ -f /opt/hermes/.hermes/SOUL.md ]; then
    echo "" >> /opt/hermes/.hermes/SOUL.md
    echo "<!-- Memory OS additions -->" >> /opt/hermes/.hermes/SOUL.md
    cat /opt/hermes/memory-os/modifications/execution-agent-protocol.md >> /opt/hermes/.hermes/SOUL.md
fi
```

### 3.9. Настройка cron

```bash
(crontab -l 2>/dev/null; echo "0 * * * * cd /opt/hermes/memory-os && export REDIS_PASSWORD=26a7b9ccfc87717cf1e7b5e1ebf514a8 && source .venv/bin/activate && python3 scripts/wiki_continuous_ingest.py >> /opt/hermes/.hermes/logs/wiki-ingest.log 2>&1") | crontab -
```

### 3.10. Перезапуск Hermes

```bash
sudo /home/$USER/.local/bin/hermes gateway restart
```

---

## 4. Решение проблем

### 4.1. Ошибка: Permission denied при монтировании s3fs

**Проблема:** `s3fs: MOUNTPOINT: /opt/hermes/obsidian-vault permission denied`

**Решение:**
```bash
sudo chown $USER:$USER /opt/hermes/obsidian-vault
```

### 4.2. Ошибка: allow_other only allowed if 'user_allow_other' is set

**Проблема:** `fusermount: option allow_other only allowed if 'user_allow_other' is set in /etc/fuse.conf`

**Решение:**
```bash
sudo nano /etc/fuse.conf
# Раскомментируйте строку: user_allow_other
```

### 4.3. Ошибка: AuthorizationHeaderMalformed с S3

**Проблема:** `Authorization header malformed, unexpected scope: 20260619/us-east-1/s3/aws4_request`

**Решение:**
```bash
# Укажите правильный регион и используйте sigv4
s3fs obsidian /opt/hermes/obsidian-vault \
  -o endpoint=garage \
  -o sigv4 \
  -o use_path_request_style
```

### 4.4. Ошибка: pip install --break-system-packages

**Проблема:** Ubuntu блокирует системную установку пакетов (PEP 668)

**Решение:**
```bash
# Используйте виртуальное окружение
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Или используйте uv
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

### 4.5. Ошибка: Vector dimension error (768 vs 4096)

**Проблема:** `Vector dimension error: expected dim: 4096, got 768`

**Причина:** `nomic-embed-text` выдаёт векторы размерности 768, а коллекция Qdrant настроена на 4096

**Решение:**
```bash
# Вариант 1: Использовать другую модель эмбеддингов (OpenRouter/Polza.ai)
# Вариант 2: Пересоздать коллекцию с размерностью 768
curl -X DELETE "http://localhost:6333/collections/knowledge_base"
curl -X PUT "http://localhost:6333/collections/knowledge_base" \
  -H "Content-Type: application/json" \
  -d '{"vectors": {"dense": {"size": 768, "distance": "Cosine"}}}'
```

### 4.6. Ошибка: Qdrant требует API ключ

**Проблема:** `401 Client Error: Unauthorized for url: http://localhost:6333`

**Решение:**
```bash
# В docker-compose.yml отключите аутентификацию
environment:
  - QDRANT__SERVICE__API_KEY=  # Оставляем пустым
```

### 4.7. Ошибка: Redis authentication required

**Проблема:** `⚠️ Redis indisponível: Authentication required.`

**Решение:**
```bash
# Убедитесь, что REDIS_PASSWORD экспортирован
export REDIS_PASSWORD=26a7b9ccfc87717cf1e7b5e1ebf514a8
python3 scripts/wiki_continuous_ingest.py
```

### 4.8. Ошибка: This model does not support embeddings

**Проблема:** `{"error":"this model does not support embeddings"}`

**Причина:** Не все модели Ollama поддерживают эмбеддинги

**Решение:** Используйте модели, явно предназначенные для эмбеддингов:
- `nomic-embed-text` (768 dims)
- `mxbai-embed-large` (1024 dims)
- Или облачные сервисы (OpenRouter, Polza.ai)

### 4.9. Ошибка: ModuleNotFoundError: No module named 'services'

**Проблема:** Python не находит модули Memory OS

**Решение:**
```bash
# Добавьте путь к PYTHONPATH
export PYTHONPATH=/opt/hermes/memory-os:$PYTHONPATH
python3 scripts/bulk_wiki_ingest_polza.py
```

---

## 5. Проверка работы

### 5.1. Проверка Docker стека

```bash
cd /opt/hermes/memory-os/docker
docker compose ps
# Все контейнеры должны быть в статусе Up и healthy
```

### 5.2. Проверка Qdrant

```bash
curl -s http://localhost:6333/ | python3 -m json.tool
curl -s -X GET "http://localhost:6333/collections/knowledge_base" | python3 -m json.tool
```

### 5.3. Проверка Redis

```bash
docker exec docker-redis-1 redis-cli -a 26a7b9ccfc87717cf1e7b5e1ebf514a8 ping
# Должен ответить: PONG
```

### 5.4. Индексация тестового документа

```bash
echo "# Test Document

This is a test document to verify indexing works.

## Content
Memory OS should index this document." > /opt/hermes/vault/wiki/test.md

cd /opt/hermes/memory-os
source .venv/bin/activate
export EMBEDDING_API_KEY=pza_ваш_ключ_здесь
python scripts/bulk_wiki_ingest_polza.py
```

### 5.5. Проверка поиска

```bash
cd /opt/hermes/memory-os
source .venv/bin/activate
python scripts/context_enhancer.py "test" --top-k 3
```

### 5.6. Проверка через Hermes

```bash
hermes chat
# В чате спросите: "What documents are in your knowledge base?"
```

---

## 6. Настройка автоматизации

### 6.1. Синхронизация Obsidian Vault

```bash
cat > /opt/hermes/sync_obsidian.sh << 'EOF'
#!/bin/bash
VAULT_SRC="/opt/hermes/obsidian-vault"
WIKI_DEST="/opt/hermes/vault/wiki/raw/obsidian"

mkdir -p "$WIKI_DEST"
rsync -av --include="*.md" --include="*/" --exclude="*" "$VAULT_SRC/" "$WIKI_DEST/"

cd /opt/hermes/memory-os
source .venv/bin/activate
export EMBEDDING_API_KEY=pza_ваш_ключ_здесь
python scripts/bulk_wiki_ingest_polza.py --wiki-root /opt/hermes/vault/wiki
EOF

chmod +x /opt/hermes/sync_obsidian.sh

# Добавление в cron (каждые 10 минут)
(crontab -l 2>/dev/null; echo "*/10 * * * * /opt/hermes/sync_obsidian.sh >> /opt/hermes/.hermes/logs/obsidian-sync.log 2>&1") | crontab -
```

### 6.2. Регулярная индексация (каждый час)

```bash
(crontab -l 2>/dev/null; echo "0 * * * * cd /opt/hermes/memory-os && export REDIS_PASSWORD=26a7b9ccfc87717cf1e7b5e1ebf514a8 && source .venv/bin/activate && python3 scripts/wiki_continuous_ingest.py >> /opt/hermes/.hermes/logs/wiki-ingest.log 2>&1") | crontab -
```

### 6.3. Резервное копирование

```bash
cat > /opt/hermes/backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/opt/hermes/backups"
mkdir -p "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/hermes_backup_$(date +%Y%m%d_%H%M%S).tar.gz" \
  /opt/hermes/.hermes \
  /opt/hermes/vault \
  /opt/hermes/memory-os/.env
EOF
chmod +x /opt/hermes/backup.sh
```

---

## 📌 Краткий чек-лист

- [ ] Docker и Docker Compose установлены
- [ ] Python 3.11+ установлен
- [ ] Hermes Agent установлен и работает
- [ ] Memory OS склонирован в `/opt/hermes/memory-os`
- [ ] Виртуальное окружение создано и активировано
- [ ] `.env` настроен с правильными ключами
- [ ] Docker стек запущен (redis, qdrant, worker)
- [ ] Плагин Icarus скопирован в `.hermes/plugins/`
- [ ] Коллекция Qdrant создана с правильной размерностью
- [ ] Тестовый документ проиндексирован
- [ ] Контекстный усилитель работает
- [ ] Cron задачи настроены

---

## 🔗 Полезные ссылки

- [Memory OS на GitHub](https://github.com/ClaudioDrews/memory-os)
- [Hermes Agent](https://github.com/ClaudioDrews/hermes-agent)
- [Qdrant Documentation](https://qdrant.tech/documentation/)
- [Ollama](https://ollama.ai/)
- [Polza.ai](https://polza.ai) (альтернатива OpenRouter)

---

## 📝 Примечания

1. **Размерность эмбеддингов** должна совпадать в `.env` и коллекции Qdrant
2. **API ключи** храните в `.env` и никогда не коммитьте в Git
3. **s3fs** может быть медленным — для больших объёмов рассмотрите rclone
4. **Контекстное окно** может переполняться при активном исследовании — используйте делегирование задач

---

*Инструкция составлена на основе реального опыта установки Memory OS на Ubuntu сервер. Если вы нашли ошибку или хотите дополнить инструкцию — создайте Issue или Pull Request в репозитории.*