microdao-daarion/docs/NODA2-MEMORY-SETUP.md

🧠 Модуль Пам'яті для Агента Sofiia на NODA2

📊 Архітектура Пам'яті DAARION

Трирівнева система пам'яті:

┌─────────────────────────────────────────────────────────────┐
│                     SOFIIA MEMORY STACK                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Qdrant     │  │  PostgreSQL  │  │    Neo4j     │     │
│  │   (Vector)   │  │ (Relational) │  │   (Graph)    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│        │                  │                  │             │
│        └──────────────────┼──────────────────┘             │
│                           │                                │
│                  ┌────────▼────────┐                      │
│                  │ Memory Service  │                      │
│                  │    (:8000)      │                      │
│                  └─────────────────┘                      │
│                           │                                │
│                  ┌────────▼────────┐                      │
│                  │  Sofiia Agent   │                      │
│                  │   (OpenClaw)    │                      │
│                  └─────────────────┘                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

1. Векторна Пам'ять (Qdrant)

Колекції для Sofiia:

Колекція	Призначення	Dimension
sofiia_messages	Історія повідомлень діалогів	1024
sofiia_docs	Документи та knowledge base	1024
sofiia_memory_items	Long-term memory items	1024
sofiia_user_context	Контекст користувачів	1024

Embedding model: Cohere embed-multilingual-v3.0 (1024 dimensions)

Що зберігається:

• Повідомлення користувачів та відповіді Sofiia
• Документація проектів
• Контекстні дані про користувачів
• Long-term memories (важливі факти, рішення)

---

2. Реляційна Пам'ять (PostgreSQL)

Таблиця user_facts:

Поле	Тип	Опис
fact_id	UUID	Унікальний ID
user_id	String	ID користувача
team_id	String	ID команди/DAO
agent_id	String	"sofiia"
fact_key	String	Ключ факту
fact_value	Text	Текстове значення
fact_value_json	JSONB	Структуровані дані

Приклади фактів:

• name: "Олександр"
• preferences: {"language": "uk", "style": "formal"}
• chat_event:2026-02-22: "Обговорювали архітектуру DAARION"

---

3. Графова Пам'ять (Neo4j)

Node types:

• Agent - Sofiia
• User - Користувачі
• Channel - Telegram, Slack, etc.
• Message - Повідомлення
• Topic - Теми розмов
• Project - Проєкти (DAARION, NODA2, etc.)

Relationships:

(User)-[:SENT]->(Message)
(Sofiia)-[:RESPONDED]->(Message)
(Message)-[:IN_CHANNEL]->(Telegram)
(Message)-[:ABOUT]->(Architecture)
(Message)-[:REFERENCES]->(Project:DAARION)

Що дає:

• Зв'язки між користувачами та темами
• Історія розмов по проектах
• Виявлення залежностей

---

🎯 Варіанти налаштування на NODA2:

Варіант A: Локальна пам'ять (ПОВНА НЕЗАЛЕЖНІСТЬ) ✨

Переваги:

• ✅ Повна ізоляція від NODA1
• ✅ Швидкий доступ (локально)
• ✅ Можна тестувати без впливу на прод
• ✅ Dev-середовище

Недоліки:

• ❌ Не бачить пам'ять з NODA1
• ❌ Потрібно більше ресурсів
• ❌ Окремі дані для dev

Що потрібно:

services:
  # Qdrant для векторної пам'яті
  qdrant-node2:
    image: qdrant/qdrant:latest
    container_name: dagi-qdrant-node2
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./data/qdrant-node2:/qdrant/storage
    environment:
      - QDRANT__SERVICE__HOST=0.0.0.0

  # PostgreSQL для реляційної пам'яті
  postgres-node2:
    image: postgres:16
    container_name: dagi-postgres-node2
    ports:
      - "5433:5432"
    environment:
      - POSTGRES_DB=daarion_memory
      - POSTGRES_USER=daarion
      - POSTGRES_PASSWORD=daarion_secret
    volumes:
      - ./data/postgres-node2:/var/lib/postgresql/data

  # Neo4j для графової пам'яті (опціонально)
  neo4j-node2:
    image: neo4j:5.15
    container_name: dagi-neo4j-node2
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      - NEO4J_AUTH=neo4j/daarion_secret
    volumes:
      - ./data/neo4j-node2:/data

  # Memory Service
  memory-service-node2:
    build: ./services/memory-service
    container_name: dagi-memory-service-node2
    ports:
      - "8000:8000"
    environment:
      - QDRANT_HOST=qdrant-node2
      - QDRANT_PORT=6333
      - DATABASE_URL=postgresql://daarion:daarion_secret@postgres-node2:5432/daarion_memory
      - NEO4J_URI=bolt://neo4j-node2:7687
      - COHERE_API_KEY=${COHERE_API_KEY}
    depends_on:
      - qdrant-node2
      - postgres-node2

---

Варіант B: Підключення до NODA1 (РЕПЛІКА) 🔄

Переваги:

• ✅ Бачить пам'ять з NODA1
• ✅ Економія ресурсів
• ✅ Read-replica для аналітики
• ✅ Реальний прод-контекст

Недоліки:

• ❌ Залежність від NODA1
• ❌ Мережева затримка
• ❌ Не можна писати (read-only)

Що потрібно:

services:
  # Memory Service підключається до NODA1
  memory-service-node2:
    build: ./services/memory-service
    container_name: dagi-memory-service-node2
    ports:
      - "8000:8000"
    environment:
      # Підключення до NODA1 Qdrant
      - QDRANT_HOST=144.76.224.179
      - QDRANT_PORT=6333
      
      # Підключення до NODA1 PostgreSQL (read replica)
      - DATABASE_URL=postgresql://daarion_reader:***@144.76.224.179:5432/daarion_memory
      
      # Підключення до NODA1 Neo4j (read replica)
      - NEO4J_URI=bolt://144.76.224.179:7687
      
      - READ_ONLY_MODE=true
      - COHERE_API_KEY=${COHERE_API_KEY}

---

Варіант C: Гібридний (РЕКОМЕНДОВАНО) ⭐

Переваги:

• ✅ Локальна пам'ять для dev/test
• ✅ Можливість підключитись до NODA1 за потреби
• ✅ Гнучкість
• ✅ Повна ізоляція для експериментів

Архітектура:

NODA2 (Development)
├── Local Memory Stack
│   ├── Qdrant (:6333)
│   ├── PostgreSQL (:5433)
│   └── Memory Service (:8000)
│
└── Optional: Remote NODA1 Access
    └── Environment variable switch

---

🚀 Рекомендація: Почати з Варіанту C

Крок 1: Створити docker-compose.memory-node2.yml

cd /Users/apple/github-projects/microdao-daarion

Файл: docker-compose.memory-node2.yml

Крок 2: Отримати Cohere API Key

Для embedding моделі потрібен ключ:

1. Зайти на https://cohere.ai
2. Зареєструватись
3. Отримати API Key

Крок 3: Запустити Memory Stack

# Додати Cohere API Key в .env
echo "COHERE_API_KEY=your_cohere_key_here" >> .env

# Запустити
docker-compose -f docker-compose.memory-node2.yml up -d

# Перевірити
docker ps | grep -E "memory|qdrant|postgres"

Крок 4: Налаштувати Sofiia для використання пам'яті

В OpenClaw конфігурації додати:

{
  "agents": {
    "list": [
      {
        "id": "sofiia",
        "model": {
          "primary": "xai/grok-4-1-fast-reasoning"
        },
        "memory": {
          "enabled": true,
          "serviceUrl": "http://localhost:8000",
          "collections": {
            "messages": "sofiia_messages",
            "docs": "sofiia_docs",
            "memory": "sofiia_memory_items",
            "context": "sofiia_user_context"
          }
        }
      }
    ]
  }
}

---

📝 Приклад використання пам'яті Sofiia:

Збереження повідомлення:

await memory_client.save_memory(
    agent_id="sofiia",
    user_id="telegram:123456",
    channel_id="telegram:sofiia",
    content="User asked about DAARION architecture",
    role="user",
    metadata={
        "topic": "architecture",
        "intent": "question",
        "project": "DAARION"
    }
)

Отримання контексту:

context = await memory_client.get_context(
    agent_id="sofiia",
    user_id="telegram:123456",
    query="архітектура",
    limit=10
)

Збереження факту:

await memory_client.save_fact(
    agent_id="sofiia",
    user_id="telegram:123456",
    fact_key="preferences",
    fact_value_json={
        "language": "uk",
        "style": "technical",
        "projects": ["DAARION", "NODA2"]
    }
)

---

📊 Статистика пам'яті (для моніторингу):

-- Кількість фактів для Sofiia
SELECT COUNT(*) FROM user_facts WHERE agent_id = 'sofiia';

-- Останні повідомлення
SELECT * FROM user_facts 
WHERE agent_id = 'sofiia' 
ORDER BY created_at DESC 
LIMIT 10;

---

🎯 Наступні кроки:

1. ✅ Ознайомитись з архітектурою пам'яті (готово!)
2. ⏳ Отримати Cohere API Key
3. ⏳ Створити docker-compose.memory-node2.yml
4. ⏳ Запустити Memory Stack
5. ⏳ Налаштувати OpenClaw для підключення
6. ⏳ Протестувати збереження та пошук

---

Який варіант цікавить вас більше? Можу допомогти з реалізацією! 🚀