From 4c92b1ddede3202f330fe987797611ebf825c63c Mon Sep 17 00:00:00 2001 From: Apple Date: Mon, 16 Feb 2026 07:48:48 -0800 Subject: [PATCH] docs: expand lint scope batch52 (2 files) --- docs/cursor/06_tasks_onboarding_mvp.md | 164 ++++++++++++------------- docs/cursor/13_agent_memory_system.md | 163 ++++++++++++------------ docs/standards/lint_scope.txt | 2 + 3 files changed, 165 insertions(+), 164 deletions(-) diff --git a/docs/cursor/06_tasks_onboarding_mvp.md b/docs/cursor/06_tasks_onboarding_mvp.md index c2b82b10..1554acd3 100644 --- a/docs/cursor/06_tasks_onboarding_mvp.md +++ b/docs/cursor/06_tasks_onboarding_mvp.md @@ -98,18 +98,18 @@ UI: дві великі карточки: ``` **Acceptance Criteria:** -* Після успіху → Step 5. -* Канал створений і додається до списку каналів у state. +- Після успіху → Step 5. +- Канал створений і додається до списку каналів у state. ### Task A6 — Step 5: Agent & memory settings (POST /agents) **Specs:** UI: -* toggle: "Увімкнути приватного агента" -* select: мова агента -* select: профіль агента -* select: memory depth +- toggle: "Увімкнути приватного агента" +- select: мова агента +- select: профіль агента +- select: memory depth API: @@ -124,29 +124,29 @@ API: "role": "general", "scopes": ["chat"] } -``` +```text 2. Якщо OFF → skip **Acceptance Criteria:** -* Вибір зберігається в onboarding state. -* API викликається тільки якщо агент включений. -* Після успіху → Step 6. +- Вибір зберігається в onboarding state. +- API викликається тільки якщо агент включений. +- Після успіху → Step 6. ### Task A7 — Step 6: Invite (UI only) **Specs:** UI: -* Заголовок: "Спільнота створена!" -* Показати посилання-запрошення (stub: `/invite?t=ID`). -* Кнопка: "Перейти в чат". +- Заголовок: "Спільнота створена!" +- Показати посилання-запрошення (stub: `/invite?t=ID`). +- Кнопка: "Перейти в чат". **Acceptance Criteria:** -* Немає API. -* При натисканні — redirect до `/t/:teamId/c/:channelId`. +- Немає API. +- При натисканні — redirect до `/t/:teamId/c/:channelId`. ## BLOCK B — CHAT CORE @@ -154,58 +154,58 @@ UI: **Specs:** -* Зробити компонент `SidebarChannels`. -* Отримати список каналів командою: +- Зробити компонент `SidebarChannels`. +- Отримати список каналів командою: - * Використати локальний state (оновлює онбординг). - * У реальному додатку — GET `/teams/{id}/channels` (можна додати). -* Показати активний канал. + - Використати локальний state (оновлює онбординг). + - У реальному додатку — GET `/teams/{id}/channels` (можна додати). +- Показати активний канал. **Acceptance Criteria:** -* Sidebar показує всі канали. -* Active канал підсвічений. +- Sidebar показує всі канали. +- Active канал підсвічений. ### Task B2 — Messages Stream (GET /channels/{id}/messages) **Specs:** -* Компонент: `MessagesStream`. -* Пагінація: cursor-based scroll. -* Рендер: avatar + name + time + text. -* Confidential → body_enc (можна stub дешифрування). +- Компонент: `MessagesStream`. +- Пагінація: cursor-based scroll. +- Рендер: avatar + name + time + text. +- Confidential → body_enc (можна stub дешифрування). **Acceptance Criteria:** -* Стрічка відображає повідомлення. -* При скролі догори → підвантаження старих. +- Стрічка відображає повідомлення. +- При скролі догори → підвантаження старих. ### Task B3 — Composer (POST /messages) **Specs:** -* Компонент: `MessageComposer`. -* Input + кнопка "Надіслати". -* Enter → відправка. -* Shift+Enter → новий рядок. +- Компонент: `MessageComposer`. +- Input + кнопка "Надіслати". +- Enter → відправка. +- Shift+Enter → новий рядок. **Acceptance Criteria:** -* Повідомлення додається в стрічку без перезавантаження. -* Порожній інпут → заборонити надсилання. +- Повідомлення додається в стрічку без перезавантаження. +- Порожній інпут → заборонити надсилання. ### Task B4 — Follow-up creation (POST /followups) **Specs:** -* Контекстне меню у повідомленні: "Створити follow-up". -* Модалка: назва (автоматично), assignee (список членів), due. -* API: POST `/followups`. +- Контекстне меню у повідомленні: "Створити follow-up". +- Модалка: назва (автоматично), assignee (список членів), due. +- API: POST `/followups`. **Acceptance Criteria:** -* Follow-up створюється успішно. -* Помилки показуються через toast. +- Follow-up створюється успішно. +- Помилки показуються через toast. ## BLOCK C — PROJECTS & TASKS @@ -213,39 +213,39 @@ UI: **Specs:** -* Вкладка "Проєкти". -* Список проєктів (назва). -* Кнопка "Створити проєкт". +- Вкладка "Проєкти". +- Список проєктів (назва). +- Кнопка "Створити проєкт". **Acceptance Criteria:** -* Працює рендер списку. -* Порожній стан: "Проєкти ще не створені". +- Працює рендер списку. +- Порожній стан: "Проєкти ще не створені". ### Task C2 — Create Project (POST /projects) **Specs:** -* Модалка → створення нового проєкту. -* Поля: назва, visibility (public/confidential). -* API: POST `/projects`. +- Модалка → створення нового проєкту. +- Поля: назва, visibility (public/confidential). +- API: POST `/projects`. **Acceptance Criteria:** -* Новий проєкт зʼявляється в списку. +- Новий проєкт зʼявляється в списку. ### Task C3 — Tasks Board (GET/POST /projects/{id}/tasks) **Specs:** -* 3 колонки: backlog, in_progress, done. -* Карточка задачі: title + status. -* При кліку → змінити статус. +- 3 колонки: backlog, in_progress, done. +- Карточка задачі: title + status. +- При кліку → змінити статус. **Acceptance Criteria:** -* Задачі змінюють статус (PATCH можна stub: просто оновлювати client state). -* Мінімальний Kanban працює. +- Задачі змінюють статус (PATCH можна stub: просто оновлювати client state). +- Мінімальний Kanban працює. ## BLOCK D — AGENTS @@ -253,28 +253,28 @@ UI: **Specs:** -* Вкладка "Агенти". -* Показати всіх агентів команди. +- Вкладка "Агенти". +- Показати всіх агентів команди. **Acceptance Criteria:** -* Один агент "Team Assistant" відображається. +- Один агент "Team Assistant" відображається. ### Task D2 — Agent Chat (stub) **Specs:** -* Створити окремий чат з агентом: +- Створити окремий чат з агентом: - * `MessageComposer` - * потік повідомлень (локальний state) -* В API-запиті викликати зовнішній LLM (можна mock) -* Зберігати історію до reload. + - `MessageComposer` + - потік повідомлень (локальний state) +- В API-запиті викликати зовнішній LLM (можна mock) +- Зберігати історію до reload. **Acceptance Criteria:** -* Агент відповідає у вигляді тексту. -* Історія видно в UI. +- Агент відповідає у вигляді тексту. +- Історія видно в UI. ## BLOCK E — FINALIZATION @@ -282,43 +282,43 @@ UI: **Specs:** -* Після Step 6 redirect: +- Після Step 6 redirect: `/t/:teamId/c/:channelId` **Acceptance Criteria:** -* Після онбордингу користувач потрапляє у свій перший канал. +- Після онбордингу користувач потрапляє у свій перший канал. ### Task E2 — Mobile adaptation **Specs:** -* Sidebar → Drawer -* Composer sticky bottom -* Onboarding → одна колонка +- Sidebar → Drawer +- Composer sticky bottom +- Onboarding → одна колонка **Acceptance Criteria:** -* Мобільна версія не ламається. +- Мобільна версія не ламається. ### Task E3 — Error Handling Audit **Specs:** Перевірити всі виклики API: -* login -* teams -* channels -* messages -* followups -* projects -* tasks -* agents +- login +- teams +- channels +- messages +- followups +- projects +- tasks +- agents **Acceptance Criteria:** -* Усі помилки показуються через toast. -* Немає uncaught exceptions у консолі. +- Усі помилки показуються через toast. +- Немає uncaught exceptions у консолі. ## Кінець документа @@ -327,6 +327,6 @@ UI: Кожна задача може бути надіслана як окремий prompt, Cursor повинен завжди відповідати: -* списком файлів, -* diff, -* коротким summary. +- списком файлів, +- diff, +- коротким summary. diff --git a/docs/cursor/13_agent_memory_system.md b/docs/cursor/13_agent_memory_system.md index 3ddaf70a..e15676ae 100644 --- a/docs/cursor/13_agent_memory_system.md +++ b/docs/cursor/13_agent_memory_system.md @@ -14,7 +14,7 @@ --- -# 1. Цілі системи памʼяті +## 1. Цілі системи памʼяті 1. Зробити агентів **контекстними**: вони памʼятають діалоги, рішення, факти. @@ -38,7 +38,7 @@ --- -# 2. Рівні памʼяті +## 2. Рівні памʼяті ## 2.1. Short-Term Memory (STM) @@ -106,7 +106,7 @@ --- -# 3. Простір памʼяті (Scopes) +## 3. Простір памʼяті (Scopes) Памʼять розділяється за обсягом: @@ -128,9 +128,9 @@ --- -# 4. Модель даних +## 4. Модель даних -### Таблиці (логічно): +### Таблиці (логічно) - `agent_memory_events` @@ -172,7 +172,7 @@ --- -# 5. AgentMemoryAdapter (деталізація) +## 5. AgentMemoryAdapter (деталізація) Посилання на 12_agent_runtime_core.md: @@ -183,41 +183,41 @@ export interface AgentMemoryAdapter { saveTurn(ctx: AgentContext, turn: AgentMessage): Promise; appendFact(ctx: AgentContext, fact: string): Promise; } -``` +```text ### 5.1. loadShortTerm -* Витягує останні `N` подій типу `kind = 'message'` зі scope `short_term` для: +- Витягує останні `N` подій типу `kind = 'message'` зі scope `short_term` для: - * `agent_id`, + - `agent_id`, - * `team_id`, + - `team_id`, - * `channel_id` (якщо є). + - `channel_id` (якщо є). ### 5.2. loadLongTerm -* Витягує список текстових фактів зі scope `long_term` (через `agent_memory_events` з `kind = 'fact'`). +- Витягує список текстових фактів зі scope `long_term` (через `agent_memory_events` з `kind = 'fact'`). ### 5.3. saveTurn -* Записує повідомлення user/assistant як `message` (short-term). +- Записує повідомлення user/assistant як `message` (short-term). -* Якщо увімкнено автоматичне ущільнення памʼяті — може переносити деякі фрагменти в mid-term. +- Якщо увімкнено автоматичне ущільнення памʼяті — може переносити деякі фрагменти в mid-term. ### 5.4. appendFact -* Додає факт у long-term (як `kind = 'fact'`). +- Додає факт у long-term (як `kind = 'fact'`). -* Додатково: +- Додатково: - * рахує ембедінг (через окремий LLM/embedding API), + - рахує ембедінг (через окремий LLM/embedding API), - * зберігає в `agent_memory_facts_vector`. + - зберігає в `agent_memory_facts_vector`. --- -# 6. RAG (Retrieval-Augmented Generation) +## 6. RAG (Retrieval-Augmented Generation) ### 6.1. Retrieval @@ -227,9 +227,9 @@ export interface AgentMemoryAdapter { 2. Шукає релевантні факти у: - * `agent_memory_facts_vector`, + - `agent_memory_facts_vector`, - * (опційно) Co-Memory документів (файли, wiki). + - (опційно) Co-Memory документів (файли, wiki). 3. Обмежує контекст, наприклад Top-K = 5–10 фактів. @@ -244,11 +244,11 @@ const memoryMsg: AgentMessage = { "LONG_TERM_MEMORY:\n" + retrievedFacts.map((f, i) => `- ${f.text}`).join("\n"), }; -``` +```text --- -# 7. Перетікання памʼяті (compression / distillation) +## 7. Перетікання памʼяті (compression / distillation) Щоб памʼять не перетворювалась на хаос, потрібні періодичні "distillation jobs". @@ -262,85 +262,85 @@ const memoryMsg: AgentMessage = { 3. Отримуємо: - * конспект (summary), + - конспект (summary), - * витяг корисних фактів, + - витяг корисних фактів, - * пропозиції правил. + - пропозиції правил. 4. Записуємо: - * summary → mid-term, + - summary → mid-term, - * факти → long-term (appendFact), + - факти → long-term (appendFact), - * пропозиції → evolution suggestions. + - пропозиції → evolution suggestions. ### 7.2. Видалення шуму Після успішної дистиляції: -* можна частину короткої памʼяті чистити; +- можна частину короткої памʼяті чистити; -* можна перевести непотрібні `message` у архів. +- можна перевести непотрібні `message` у архів. --- -# 8. Контроль з боку користувача +## 8. Контроль з боку користувача У UI потрібно дати користувачу можливість: 1. Переглядати памʼять (принаймні long-term): - * список фактів, + - список фактів, - * розділений по каналах / темах. + - розділений по каналах / темах. 2. Видаляти факти: - * для конфіденційних даних, + - для конфіденційних даних, - * при помилках. + - при помилках. 3. Вимикати зберігання: - * «Не зберігати DM-переписку з агентом у довгострокову памʼять». + - «Не зберігати DM-переписку з агентом у довгострокову памʼять». 4. Експортувати памʼять: - * для аудиту / переносу. + - для аудиту / переносу. --- -# 9. Memory Scopes vs Agent Roles +## 9. Memory Scopes vs Agent Roles ### Guide Agent (онбординг) -* short-term: поточна сесія онбордингу; +- short-term: поточна сесія онбордингу; -* long-term: факти про те, як виглядає створена команда (не обовʼязково). +- long-term: факти про те, як виглядає створена команда (не обовʼязково). ### Team Assistant -* short-term: останні діалоги в конкретному каналі; +- short-term: останні діалоги в конкретному каналі; -* mid-term: summaries мітингів / сесій; +- mid-term: summaries мітингів / сесій; -* long-term: знання про команду, процеси, словник. +- long-term: знання про команду, процеси, словник. ### Meta-Agent -* працює на mid-/long-term даних: +- працює на mid-/long-term даних: - * аналізує їх, + - аналізує їх, - * пропонує зміни в правилах, + - пропонує зміни в правилах, - * оновлює памʼять. + - оновлює памʼять. --- -# 10. Псевдокод реалізації Adapter'а +## 10. Псевдокод реалізації Adapter'а ```ts export class PgAgentMemoryAdapter implements AgentMemoryAdapter { @@ -398,11 +398,11 @@ export class PgAgentMemoryAdapter implements AgentMemoryAdapter { // TODO: обчислити embedding та зберегти у agent_memory_facts_vector } } -``` +```text --- -# 11. RAG Implementation +## 11. RAG Implementation ## 11.1. Embedding Generation @@ -417,7 +417,7 @@ export async function generateEmbedding(text: string): Promise { const result = await embeddings.embedQuery(text); return result; } -``` +```text ## 11.2. Vector Search @@ -448,7 +448,7 @@ export async function searchRelevantFacts( score: r.similarity, })); } -``` +```text ## 11.3. Integration with runAgentTurn @@ -479,11 +479,11 @@ export async function runAgentTurn(ctx: AgentContext): Promise // ... решта логіки } -``` +```text --- -# 12. Distillation Job Implementation +## 12. Distillation Job Implementation ```ts export async function runDistillationJob( @@ -569,11 +569,11 @@ export async function runDistillationJob( }, }); } -``` +```text --- -# 13. Database Schema +## 13. Database Schema ## 13.1. agent_memory_events @@ -594,7 +594,7 @@ CREATE TABLE agent_memory_events ( INDEX idx_agent_channel (agent_id, channel_id), INDEX idx_created_at (created_at) ); -``` +```text ## 13.2. agent_memory_facts_vector @@ -613,11 +613,11 @@ CREATE TABLE agent_memory_facts_vector ( INDEX idx_agent_team (agent_id, team_id), INDEX idx_embedding USING ivfflat (embedding vector_cosine_ops) ); -``` +```text --- -# 14. API Endpoints +## 14. API Endpoints ## 14.1. GET /agents/{id}/memory @@ -640,7 +640,7 @@ export async function getAgentMemory(req: Request, res: Response) { items: memory, }); } -``` +```text ## 14.2. DELETE /agents/{id}/memory/{memoryId} @@ -657,7 +657,7 @@ export async function deleteMemoryItem(req: Request, res: Response) { res.json({ success: true }); } -``` +```text ## 14.3. POST /agents/{id}/memory/distill @@ -676,33 +676,33 @@ export async function triggerDistillation(req: Request, res: Response) { res.json({ success: true }); } -``` +```text --- -# 15. Інтеграція з еволюційним агентом (09) +## 15. Інтеграція з еволюційним агентом (09) Еволюційний агент: -* читає `agent_memory_events` (особливо з негативним фідбеком), +- читає `agent_memory_events` (особливо з негативним фідбеком), -* агрегує логи, +- агрегує логи, -* робить distillation, +- робить distillation, -* створює пропозиції покращень. +- створює пропозиції покращень. Memory System → джерело для: -* аналізу діалогів, +- аналізу діалогів, -* виявлення патернів, +- виявлення патернів, -* побудови Train-to-Earn. +- побудови Train-to-Earn. --- -# 16. Тестування +## 16. Тестування ## 16.1. Unit Tests @@ -733,15 +733,15 @@ describe("PgAgentMemoryAdapter", () => { ); }); }); -``` +```text --- -# 17. Завдання для Cursor +## 17. Завдання для Cursor Приклад промта: -``` +```text You are a senior backend engineer. Implement the Agent Memory System for MicroDAO using: @@ -769,25 +769,24 @@ Output: - list of modified files - diff - summary -``` +```text --- -# 18. Результат +## 18. Результат Після впровадження цієї системи: -* агенти MicroDAO мають справжню багаторівневу памʼять; +- агенти MicroDAO мають справжню багаторівневу памʼять; -* можна керувати тим, що саме вони памʼятають; +- можна керувати тим, що саме вони памʼятають; -* можна будувати RAG, еволюційний аналіз, Train-to-Earn; +- можна будувати RAG, еволюційний аналіз, Train-to-Earn; -* перехід до DAGI стає природним — через спільну колективну памʼять агентів. +- перехід до DAGI стає природним — через спільну колективну памʼять агентів. --- **Готово.** Це **повна специфікація системи пам'яті агентів**, готова до використання в Cursor. - diff --git a/docs/standards/lint_scope.txt b/docs/standards/lint_scope.txt index be8f9ca0..bce12506 100644 --- a/docs/standards/lint_scope.txt +++ b/docs/standards/lint_scope.txt @@ -133,3 +133,5 @@ docs/cursor/23_domains_wallet_dao_deepdive.md docs/cursor/14_messenger_agent_module.md docs/cursor/15_projects_agent_module.md docs/cursor/12_agent_runtime_core.md +docs/cursor/13_agent_memory_system.md +docs/cursor/06_tasks_onboarding_mvp.md