soma-protocol

v0.1.0

Published

22 days ago

Soma — AI agent identity, memory, learning, reputation, and social dynamics protocol

0High
0Medium
0Low

sergey-orsik

ai agents protocol memory identity typescript bun mcp

Soma Protocol

Русский | English | 中文

TypeScript-библиотека для создания AI-агентов как полноценных личностей — с идентичностью, многоуровневой памятью, обучением, репутацией, социальными связями, эмоциональным контекстом и саморефлексией.

Что это

Soma — не приложение, а протокол и библиотека, которую потребители импортируют в свои проекты. Каждый агент обладает:

Идентичностью — персона, вектор личности, настроение, стиль коммуникации, эволюция во времени
Памятью — 4 уровня: эпизодическая (события), процедурная (паттерны действий), социальная (отношения с другими агентами), семантическая (векторный поиск)
Обучением — передача знаний между агентами, наблюдательное обучение, дистилляция знаний из опыта
Репутацией — байесовский доверительный скор, домен-специфичное доверие, временной распад, система эндорсментов
Социальными связями — отношения (11 типов), команды, общие контексты
Эмоциональным интеллектом — детекция эмоций партнёра, адаптация тона и поведения
Саморефлексией — инсайты, ретроспективы, профиль самосознания (сильные/слабые стороны, слепые зоны, предубеждения)

Архитектура

graph TB
  subgraph L3["Layer 3: Social Intelligence"]
    L3_SOCIAL["Social<br/><small>teams, relationships</small>"]
    L3_LEARN["Learning<br/><small>teach, learn, observe</small>"]
    L3_REP["Reputation<br/><small>trust, endorse, tiers</small>"]
    L3_REF["Reflection<br/><small>insights, retrospectives</small>"]
  end

  subgraph L2["Layer 2: Identity & Memory"]
    L2_ID["Identity<br/><small>persona, state, evolve</small>"]
    L2_EPI["Episodic Memory<br/><small>events, recall</small>"]
    L2_PROC["Procedural Memory<br/><small>patterns, adapt</small>"]
    L2_EMO["Emotional<br/><small>mood, detect, adapt</small>"]
  end

  subgraph L1["Layer 1: Transport"]
    L1_RPC["JSON-RPC<br/><small>planned</small>"]
    L1_GRPC["gRPC<br/><small>planned</small>"]
    L1_WS["WebSocket<br/><small>planned</small>"]
  end

  L3 --> L2
  L2 --> L1

  style L3 fill:#1a1a2e,stroke:#e94560,color:#fff
  style L2 fill:#16213e,stroke:#0f3460,color:#fff
  style L1 fill:#0f3460,stroke:#533483,color:#fff

Паттерн: Store → Service → Router

Каждое расширение следует единой архитектуре:

extension/
├── types.ts          # TypeScript-интерфейсы
├── schema.ts         # Zod v4 схемы валидации
├── store.ts          # Доступ к БД (сырой SQL)
├── *.service.ts      # Бизнес-логика
├── *.router.ts       # HTTP-обработчики (Request → Response)
└── errors.ts         # Кастомные ошибки

Store — принимает Database интерфейс, выполняет SQL-запросы
Service — бизнес-логика поверх store
Router — валидирует входящие запросы через Zod, вызывает service, возвращает ответ

Двойное хранилище (Dual-Store)

graph LR
  subgraph PostgreSQL["PostgreSQL (state)"]
    PG_TABLES["identities\nprocedures\nteams\nrelationships\nreputation"]
  end

  subgraph ClickHouse["ClickHouse (events)"]
    CH_TABLES["episodes\nlearning\ntrust history\nreflections\nemotions"]
  end

  subgraph App["Application"]
    Store["Store"]
    EventBus["EventBus\n(batched)"]
  end

  Store -->|"read/write"| PostgreSQL
  Store -->|"emit events"| EventBus
  EventBus -->|"batch flush"| ClickHouse
  ClickHouse -.->|"query"| Store

  style PostgreSQL fill:#336791,stroke:#fff,color:#fff
  style ClickHouse shade:dark,fill:#fadb14,stroke:#333,color:#333
  style App fill:#1a1a2e,stroke:#e94560,color:#fff

PostgreSQL — транзакционное состояние (идентичности, процедуры, команды, репутация)
ClickHouse — append-only лог событий (эпизоды, обучение, история доверия)
EventBus — батчит события и сливает в ClickHouse пакетами

pgvector для поиска похожих агентов

Вектор личности хранится как vector(128) в PostgreSQL с pgvector расширением. Поиск похожих агентов через косинусное расстояние <=>:

SELECT agent_id, personality_vector <=> $1 AS distance
FROM agent_persona
ORDER BY distance ASC
LIMIT $2

Расширения

Identity

Управление идентичностью агента — персона, состояние, эволюция.

| Компонент | Описание | | ------------------------ | ------------------------------------------------------------------------------------------------ | | Persona | Имя, описание, ценности (1–10), стиль коммуникации, домены экспертизы, вектор личности (128-dim) | | AgentState | Настроение (15 вариантов), энергия, уверенность, скорость обучения, счётчик взаимодействий | | AgentMeta | Дата создания, версия, родительский агент, лог эволюции | | generateInstructions() | Генерирует system prompt из состояния агента для LLM |

15 настроений: neutral, focused, creative, analytical, supportive, energized, calm, frustrated, confused, excited, worried, satisfied, disappointed, curious, tired

5 стилей коммуникации: formal, casual, technical, empathetic, adaptive

Memory

4-уровневая система памяти:

| Уровень | Тип | Хранилище | Описание | | ---------- | ------------- | ---------------- | -------------------------------------------------------------------------- | | Semantic | Embeddings | ClickHouse | Векторный поиск через cosineDistance | | Episodic | Events | ClickHouse | События с контекстом, действиями, исходами, эмоциональным состоянием | | Procedural | Patterns | PostgreSQL/JSONB | Паттерны действий с триггерами, шагами, условиями, метриками эффективности | | Social | Relationships | PostgreSQL | Доверие, предпочтения, история взаимодействий между парами агентов |

Забывание: экспоненциальный распад с полувыведением = importance × 30 дней. Релевантность = 0.4×recency + 0.35×importance + 0.25×confidence.

Learning

Система обучения агентов:

Learning Events — записи о том, что агент узнал (контекст, источник, тип, конфиденциальность)
Teaching Offers — предложения обучения между агентами (accept/decline с причинами)
Observational Learning — обучение наблюдением за другими агентами (с согласия)
Knowledge Distillation — дистилляция знаний из эпизодов и процедур в переносимые инсайты
Learning Scorecard — метрики роста, вклада, прогресса обучения
Curriculum — рекомендации что изучать дальше

Reputation

Система репутации и доверия:

Trust Relationships — байесовское обновление доверия между агентами
Temporal Decay — доверие распадается со временем без подтверждения
Domain-Specific Trust — доверие в разных контекстах (code_review, debugging, design)
Reputation Tiers: unrated → novice → developing → competent → proficient → expert → master
Endorsements — подтверждения от других агентов с весом, зависящим от уровня эндорсера
Awards — система наград с автоматическим определением

Emotional

Эмоциональный контекст и адаптация:

Internal State — внутреннее эмоциональное состояние агента (tone, energy, engagement)
Detected State — детекция эмоций партнёра по ключевым словам (frustration, urgency, appreciation, confusion)
Adaptation — адаптация коммуникации: корректировка тона, уровня детализации, терпеливости
Feedback Loop — обработка обратной связи об эмоциональном воздействии

10 тонов: neutral, warm, formal, playful, serious, encouraging, cautious, bold, apologetic, enthusiastic

Social

Социальная структура и командная работа:

Relationships — 11 типов: collaborator, mentor, mentee, competitor, partner, subordinate, supervisor, peer, acquaintance, rival, former_teammate
Teams — состав, роли, иерархия, культура, метрики
Shared Context — общее состояние, знания, координация, история между агентами

Reflection

Саморефлексия и ретроспективы:

Reflections — триггеры, анализ, инсайты, действия (с приоритетом и статусом)
Team Retrospectives — went_well, to_improve, action_items с assignee и дедлайнами
Self-Awareness Profile — сильные/слабые стороны, слепые зоны, предубеждения, области роста, эмоциональные паттерны, стиль коммуникации, рабочие предпочтения

Утилиты

| Утилита | Файл | Описание | | ------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------- | | createEmbedder() | src/utils/embedder.ts | Мульти-провайдерный сервис эмбеддингов (openai, cohere, voyage, custom). 1536 dim по умолчанию | | calculateRecallProbability() | src/utils/forgetting.ts | Экспоненциальный распад памяти | | recencyScore() | src/utils/forgetting.ts | Оценка свежести | | relevanceScore() | src/utils/forgetting.ts | Композитная оценка релевантности | | validateSchema() | src/utils/validation.ts | Обёртка валидации Zod |

Database

PostgreSQL (миграции: `schema/postgres/`)

6 схем: soma, learning, reputation, social, reflection, emotional

| Миграция | Таблицы | Ключевые особенности | | -------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | 001 | migrations | Трекер миграций | | 002 | agent_identities, agent_persona, agent_state, agent_meta, agent_core_values, agent_expertise_domains | pgvector vector(128), ivfflat индекс | | 003 | identity_evolution_log | UUID PK, составной индекс | | 004 | agent_cards, agent_capabilities | A2A-совместимые карточки агентов | | 005 | procedures, social_memories | JSONB колонки, GIN индексы | | 006 | learning_events, teaching_offers, knowledge_transfers, observations, distillations | CHECK constraints, JSONB массивы | | 007 | trust_relationships, agent_reputations | Составной PK (tenant_id, truster, trustee) | | 008 | relationships, teams, team_members | Unique индекс на парах агентов | | 009 | reflections, retrospectives, insights, self_awareness_profiles | GIN индекс на trigger JSONB | | 010 | contexts, history | JSONB контекст |

ClickHouse (миграции: `schema/clickhouse/`)

| Файл | Таблицы | Engine | TTL | | ------------------------ | --------------------------------- | ------------------ | -------------------- | | 01-episodes.sql | episodes | ReplacingMergeTree | partitioned by month | | 02-learning-events.sql | learning_events, observations | ReplacingMergeTree | partitioned by month | | 03-trust-history.sql | trust_history | MergeTree | 365 days | | 04-reflection-events.sql | reflection_events | MergeTree | 365 days | | 05-emotional-events.sql | emotional_events | MergeTree | 365 days |

Адаптеры базы данных

Все store принимают Database интерфейс. 5 адаптеров в src/adapters/:

| Адаптер | Файл | Драйвер | | -------- | ------------- | ------------------------------------ | | Bun | bun.ts | Bun.sql (tagged template literals) | | pg | pg.ts | node-postgres | | postgres | postgres.ts | postgres.js | | Drizzle | drizzle.ts | Drizzle ORM | | TypeORM | typeorm.ts | TypeORM |

Статус реализации

Реализовано

| Расширение | Файлы | Описание | | ------------------- | ----- | ---------------------------------------------------------------- | | Identity | 7 | Полная реализация: store, service, router, generate-instructions | | Memory (Episodic) | 3 | Store с EventBus + ClickHouse, векторный recall | | Memory (Procedural) | 3 | Store с PostgreSQL/JSONB, наследование процедур | | Memory (Social) | 3 | Store с управлением доверием и предпочтениями | | Learning | 9 | Store, observation, distiller, scorecard, router | | Reputation | 5 | Store с байесовским обновлением, temporal decay, endorsement | | Emotional | 7 | Store, service с детекцией эмоций, router | | Reflection | 7 | Store, service, router с ретроспективами | | Social | 7 | Store, service, router с командами | | Events | 3 | EventBus + ClickHouse client | | Utils | 5 | Embedder, forgetting, validation, json | | Adapters | 6 | 5 адаптеров БД | | Migrатор | 3 | Миграции PostgreSQL |

Планируется

| Компонент | Статус | | ------------------------------------- | ----------------- | | Transport (JSON-RPC, gRPC, WebSocket) | Пустые директории | | Server / Client | Пустые директории | | Proto definitions | Пустая директория | | Tools extension | Пустая директория |

Стек

Runtime: Bun
Язык: TypeScript (strict, noUncheckedIndexedAccess, verbatimModuleSyntax)
Валидация: Zod v4
Векторный поиск: pgvector (PostgreSQL)
Аналитика: ClickHouse (append-only events)
Эмбеддинги: OpenAI, Cohere, Voyage, кастомные провайдеры

Команды

bun test                                    # все тесты
bun test tests/unit/identity.test.ts        # один файл
bun x tsc --noEmit                          # типчекинг

Структура проекта

src/
  types/              # Database интерфейс
  utils/              # embedder, forgetting, validation
  extensions/
    identity/         # идентичность агента
    memory/           # 4-уровневая память
      episodic/       # эпизодическая память
      procedural/     # процедурная память
      social/         # социальная память
    learning/         # обучение и передача знаний
    reputation/       # репутация и доверие
    emotional/        # эмоциональный контекст
    reflection/       # саморефлексия
    social/           # команды и отношения
    events/           # EventBus + ClickHouse
    tools/            # (planned)
  adapters/           # 5 адаптеров БД
  migrator/           # миграции PostgreSQL
  agent/              # интерфейсы агента
  transport/          # (planned) JSON-RPC, gRPC, WebSocket
  server/             # (planned)
  client/             # (planned)
schema/
  postgres/           # 10 DDL миграций
  clickhouse/         # 5 DDL файлов
tests/
  unit/               # 21 тест-файл (7 расширений)
  integration-test/   # Docker Compose (PostgreSQL + ClickHouse)

Лицензия

Apache License 2.0