dedinit.ru/content/posts/20260621 - memory-os installation/index.md

title, build, draft

title	build	draft
Content Placeholder	render list publishResources never never false	true

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

Содержание

1. Подготовка окружения
2. Настройка хранилищ
3. Установка Memory OS
4. Решение проблем
5. Проверка работы
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

# Установка 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

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

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

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

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

---

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

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

# Основная директория для всех данных
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:

# Установка 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. Настройка переменных окружения

# Добавьте в ~/.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. Клонирование репозитория

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

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

# Через 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

cp .env.example .env
nano .env

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

# ── 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 стека

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

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

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

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

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. Настройка базы данных

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

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

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

(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

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

---

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

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

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

Решение:

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

Решение:

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

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

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

Решение:

# Укажите правильный регион и используйте 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)

Решение:

# Используйте виртуальное окружение
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

Решение:

# Вариант 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

Решение:

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

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

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

Решение:

# Убедитесь, что 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

Решение:

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

---

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

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

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

5.2. Проверка Qdrant

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

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

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

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. Проверка поиска

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

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

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

---

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

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

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. Регулярная индексация (каждый час)

(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. Резервное копирование

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
• Hermes Agent
• Qdrant Documentation
• Ollama
• Polza.ai (альтернатива OpenRouter)

---

📝 Примечания

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

---

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