Постійна векторна пам'ять для коду Клода: Відкритий сервер MCP
Ситуація
Claude Code - це потужний AI асистент кодування, але він за своєю суттю безстанційний. Кожна нова сесія починається без знання минулих рішень, помилок або архітектури. У реальній виробничій роботі це призводить до постійного повторення, втрати контексту та уповільнення розвитку.
Проблема
Основна проблема: AI асистент, який допомагає будувати проект, не має пам'яті про його створення. Я знову відкривав ті ж самі помилки, знову пояснював ту ж архітектуру і втратив рішення, прийняті минулого тижня. Додаткова проблема: повторювані шаблони в проектах (наприклад, "ми налаштували Supabase саме так 4 рази") залишалися похованими в пам'яті сесій замість того, щоб стати повторно використовуваними, задокументованими навичками.
Рішення
Я створив memory-mcp, відкритий MCP сервер, який надає Claude Code довгострокову семантичну пам'ять. Він пропонує 8 інструментів: 4 основних інструменти пам'яті (запам'ятати, згадати, забути, статус_проекту) та 4 інструменти шаблонів навичок, які відстежують повторювані робочі шаблони та виводять кандидатів для формалізації, коли їх бачать 3+ рази.
Спогади зберігаються у вигляді векторних вбудувань розміром 1536 вимірів (OpenAI text-embedding-3-small) у Supabase PostgreSQL з pgvector. Витяг виконує пошук косинусної схожості через функцію RPC Postgres з фільтрацією на рівні SQL (поріг, проект, тип, дата, термін дії) за один раз. Відповіді на запити обмежені до ~2000 токенів, щоб захистити контекстне вікно Claude.
Сервер працює як безстанційний контейнер Docker на порту 3101 через Express + Streamable HTTP транспорт, тому кілька сесій Claude Code ділять один завжди активний екземпляр. Також доступний режим транспорту stdio для прямої інтеграції з рідним бінарним форматом. Спогади ніколи не видаляються остаточно: забути - це м'яке видалення через expires_at, і кожен запит фільтрується за статусом активної пам'яті.
Технологічний стек: Node.js 20, TypeScript 5 (строгий), Express 5, @ modelcontextprotocol/sdk, OpenAI API (text-embedding-3-small), Supabase PostgreSQL, pgvector, IVFFlat індекси, Zod валідація, Vitest, Docker Compose.
Результати
- 8 MCP інструментів випущено та протестовано від початку до кінця через HTTP
- 125 юніт-тестів з повністю змодельованими клієнтами Supabase та OpenAI
- ~2,600 рядків TypeScript у 16 вихідних файлах, 11 комітів за 11 днів
- 2 таблиці, 3 функції RPC з фільтрацією на рівні SQL перед LIMIT для коректності
- Виробничий запуск як завжди активний Docker сервіс, використовується щодня з реальними сесіями Claude Code
- Опубліковано як відкритий код на GitHub з повною документацією з налаштування, Docker Compose та посібником з усунення несправностей, що охоплює 4 задокументовані режими збоїв
Ключові інженерні рішення
1. Емпіричні пороги схожості. text-embedding-3-small виробляє нижчі косинусні оцінки, ніж вказують документи (майже ідентичні текстові оцінки 0.78–0.84). Я знизив поріг згадування до 0.25 і dedup до 0.75 на основі реальних вимірювань, задокументував правило для майбутніх функцій.
2. Фільтрація дати на рівні SQL. Фільтр since_days спочатку працював на стороні клієнта після LIMIT, що тихо пропускало нещодавні спогади, які були нижче топ N. Переміщення його в WHERE перед LIMIT гарантує коректність незалежно від обсягу даних.
3. Опис інструментів як виконувані інструкції. Опис інструментів був переписаний з "що вони роблять" на "коли їх викликати" (наприклад, "Викликати перед початком нетривіальної роботи"), тому інструменти працюють правильно без необхідності підтримувати CLAUDE.md.
4. Обхід OAuth для рідного бінарного формату Claude Code. Бінарний формат блокує HTTP MCP з'єднання, поки не завершиться відкриття OAuth. Додавання статичного токена Bearer до конфігурації MCP повністю пропускає відкриття (токен є довільним і ніколи не перевіряється на стороні сервера).
Доступно на GitHub
Повний вихідний код, інструкції з налаштування та документація з архітектури опубліковані для розробників, які хочуть відтворити або розширити систему.
Claude Code - це потужний AI асистент кодування, але він за своєю суттю безстанційний. Кожна нова сесія починається без знання минулих рішень, помилок або архітектури. У реальній виробничій роботі це призводить до постійного повторення, втрати контексту та уповільнення розвитку.
Проблема
Основна проблема: AI асистент, який допомагає будувати проект, не має пам'яті про його створення. Я знову відкривав ті ж самі помилки, знову пояснював ту ж архітектуру і втратив рішення, прийняті минулого тижня. Додаткова проблема: повторювані шаблони в проектах (наприклад, "ми налаштували Supabase саме так 4 рази") залишалися похованими в пам'яті сесій замість того, щоб стати повторно використовуваними, задокументованими навичками.
Рішення
Я створив memory-mcp, відкритий MCP сервер, який надає Claude Code довгострокову семантичну пам'ять. Він пропонує 8 інструментів: 4 основних інструменти пам'яті (запам'ятати, згадати, забути, статус_проекту) та 4 інструменти шаблонів навичок, які відстежують повторювані робочі шаблони та виводять кандидатів для формалізації, коли їх бачать 3+ рази.
Спогади зберігаються у вигляді векторних вбудувань розміром 1536 вимірів (OpenAI text-embedding-3-small) у Supabase PostgreSQL з pgvector. Витяг виконує пошук косинусної схожості через функцію RPC Postgres з фільтрацією на рівні SQL (поріг, проект, тип, дата, термін дії) за один раз. Відповіді на запити обмежені до ~2000 токенів, щоб захистити контекстне вікно Claude.
Сервер працює як безстанційний контейнер Docker на порту 3101 через Express + Streamable HTTP транспорт, тому кілька сесій Claude Code ділять один завжди активний екземпляр. Також доступний режим транспорту stdio для прямої інтеграції з рідним бінарним форматом. Спогади ніколи не видаляються остаточно: забути - це м'яке видалення через expires_at, і кожен запит фільтрується за статусом активної пам'яті.
Технологічний стек: Node.js 20, TypeScript 5 (строгий), Express 5, @ modelcontextprotocol/sdk, OpenAI API (text-embedding-3-small), Supabase PostgreSQL, pgvector, IVFFlat індекси, Zod валідація, Vitest, Docker Compose.
Результати
- 8 MCP інструментів випущено та протестовано від початку до кінця через HTTP
- 125 юніт-тестів з повністю змодельованими клієнтами Supabase та OpenAI
- ~2,600 рядків TypeScript у 16 вихідних файлах, 11 комітів за 11 днів
- 2 таблиці, 3 функції RPC з фільтрацією на рівні SQL перед LIMIT для коректності
- Виробничий запуск як завжди активний Docker сервіс, використовується щодня з реальними сесіями Claude Code
- Опубліковано як відкритий код на GitHub з повною документацією з налаштування, Docker Compose та посібником з усунення несправностей, що охоплює 4 задокументовані режими збоїв
Ключові інженерні рішення
1. Емпіричні пороги схожості. text-embedding-3-small виробляє нижчі косинусні оцінки, ніж вказують документи (майже ідентичні текстові оцінки 0.78–0.84). Я знизив поріг згадування до 0.25 і dedup до 0.75 на основі реальних вимірювань, задокументував правило для майбутніх функцій.
2. Фільтрація дати на рівні SQL. Фільтр since_days спочатку працював на стороні клієнта після LIMIT, що тихо пропускало нещодавні спогади, які були нижче топ N. Переміщення його в WHERE перед LIMIT гарантує коректність незалежно від обсягу даних.
3. Опис інструментів як виконувані інструкції. Опис інструментів був переписаний з "що вони роблять" на "коли їх викликати" (наприклад, "Викликати перед початком нетривіальної роботи"), тому інструменти працюють правильно без необхідності підтримувати CLAUDE.md.
4. Обхід OAuth для рідного бінарного формату Claude Code. Бінарний формат блокує HTTP MCP з'єднання, поки не завершиться відкриття OAuth. Додавання статичного токена Bearer до конфігурації MCP повністю пропускає відкриття (токен є довільним і ніколи не перевіряється на стороні сервера).
Доступно на GitHub
Повний вихідний код, інструкції з налаштування та документація з архітектури опубліковані для розробників, які хочуть відтворити або розширити систему.
Харків 
Вільний для роботи