Memex

Собирайте разрозненные разговоры Codex, извлекайте долговечные знания, связывайте их, индексируйте и возвращайте нужное воспоминание, когда это важно.

Memex — это локальная персональная система знаний для Codex с приоритетом локальных данных. Она превращает локальные сеансы в доступный для поиска архив разговоров, долговечные факты, граф знаний на основе онтологии и ограниченный контекст, который Codex может использовать в дальнейшей работе.

한국어 README · Документация · Установка и эксплуатация · Архитектура · Схема

Memex — это независимый проект, нативный для Codex, происходящий от jung-wan-kim/memory-bank под лицензией MIT, который, в свою очередь, происходит от obra/episodic-memory. Он сохраняет возможности системы знаний, а не код совместимости с Claude Code. См. происхождение и миграцию.

Почему 0.1.0?

0.1.0 — правильный первый публичный релиз. Набор функций значителен и протестирован, но репозиторий недавно стал независимым, и его маркетплейс Codex, хостовый адаптер и контракты установки могут ещё измениться до стабильной версии 1.0.0. Версия 1.0.0 будет означать, что эти публичные контракты намеренно стабильны, а не просто наличие множества функций.

Related MCP server: coding-memory-mcp

Возможности

• Семантический, FTS5/BM25 и гибридный поиск по истории разговоров Codex

• Детерминированный анализ всей истории без вызова LLM

• Инкрементальное извлечение фактов, пороги уверенности, консолидация, ревизии и происхождение

• Онтология доменов/категорий и типизированные отношения в графе знаний

• Изоляция области действия проекта, глобальной и явно запрошенной области всех проектов

• Обход графа на 1–3 хопа и межпроектные инсайты

• Ограниченная инъекция RAG-контекста с релевантностью и дедупликацией по сеансам

• Прозрачное ограниченное чтение сжатых архивов .jsonl.zst

• Девять инструментов MCP для разговоров, фактов, онтологии, графа и происхождения

• Три навыка Codex для извлечения, анализа истории и рабочих процессов панели мониторинга

• Веб-интерфейс только через loopback с фактами, состоянием конвейера и 3D-галактикой знаний

• Нативные для Codex хуки SessionStart, UserPromptSubmit и SessionEnd

Архитектура вкратце

flowchart LR
    R[Codex rollout JSONL] --> S[Sync and parser]
    S --> A[Immutable local archive]
    S --> C[(Conversation index)]
    C --> X[Incremental fact extraction]
    X --> F[(Facts and revisions)]
    F --> O[(Ontology and typed relations)]
    C --> Q[Hybrid retrieval]
    F --> Q
    O --> Q
    Q --> M[MCP tools and skills]
    Q --> H[Prompt context hook]
    C --> UI[Loopback Web UI]
    F --> UI
    O --> UI

Исходные прогоны доступны только для чтения. Архивы, индексы SQLite/FTS/векторные, факты и данные графа являются производным локальным состоянием. Работа с поддержкой моделей выполняется через изолированный, эфемерный локальный codex exec; нет запасного варианта на Claude или отдельного поставщика API-ключей.

Подробные механизмы см. в:

• Системная архитектура

• Жизненный цикл разговора

• Жизненный цикл фактов

• Граф знаний

• Поиск и инъекция контекста

• MCP и навыки

• Веб-интерфейс и 3D-визуализация

Требования

• Node.js 22.15 или новее

• Аутентифицированный Codex CLI

• macOS или Linux для текущего хука и среды выполнения Unix-socket

Плагин использует встроенный в Node лаунчер npx для разрешения последней версии среды выполнения из BongSuCHOI/memex#main в изолированном кэше npm. Он не клонирует и не собирает код в вашем проекте, не устанавливает глобальный пакет и не записывает зависимости в кэш плагинов Codex.

Рекомендуемая установка

Установите напрямую из публичного репозитория:

codex plugin marketplace add BongSuCHOI/memex
codex plugin add memex@memex

Это полная установка для пользователя. Она устанавливает манифест плагина, три навыка, объявление MCP, хуки жизненного цикла, лаунчер CLI и лаунчер UI. Первый вызов среды выполнения может занять больше времени, пока npx заполняет свой кэш нативными зависимостями SQLite, векторных вычислений и эмбеддингов.

Существующий ручной процесс маркетплейса

Внешняя структура маркетплейса по-прежнему поддерживается для разработки и автономного/локального тестирования:

memex-local-marketplace/
├── .agents/plugins/marketplace.json
└── plugins/memex -> /absolute/path/to/memex

Укажите его запись на ./plugins/memex, зарегистрируйте его с помощью codex plugin marketplace add /absolute/path/memex-local-marketplace, установите memex@<marketplace-name>. Установщик из исходников остаётся доступным для проверки локальной разработки. Полное поведение JSON и отката описано в руководстве по эксплуатации.

Первичная настройка

После установки перезапустите Codex, чтобы недавно установленные MCP-сервер, навыки и управляемые плагином хуки загрузились в новой сессии. Функции внутри сессии (поиск по разговорам, извлечение/инъекция фактов, инструменты MCP) затем работают без дополнительной настройки. Чтобы использовать CLI memex напрямую в терминале, учтите, что одна лишь регистрация плагина не помещает бинарный файл memex в PATH — выполните эту команду один раз, чтобы установить постоянный шим (никогда не глобальную установку; PATH проверяется и выводится):

npx --yes --package=github:BongSuCHOI/memex#main memex setup --install-cli

Это создаёт ~/.local/bin/memex, который вы используете для разовой настройки корпуса:

memex setup
memex sync
memex backfill all
memex status

memex setup проверяет действующую функцию Codex memories. Когда встроенная Memory включена, Memex объясняет риск двойной/конфликтующей памяти и рекомендует отключить её. Интерактивные терминалы запрашивают подтверждение; автоматизация и неинтерактивные оболочки никогда не изменяют настройку без явного флага подтверждения memex setup --disable-codex-memory. Изменение использует собственную команду Codex codex features disable memories и проверяется после выполнения.

Что делает каждый этап:

1. sync читает существующие $CODEX_HOME/sessions, архивирует новые прогоны и строит индексы поиска по разговорам.

2. backfill all выполняет каждый этап отложенных работ по порядку — extract извлекает долговечные факты из уже проиндексированных обменов, ontology классифицирует факты и строит структуру графа, а embeddings заполняет недостающие семантические векторы. Каждый этап по умолчанию выполняется на переднем плане, поэтому завершение непосредственно наблюдаемо; оркестрация останавливается на первом упавшем этапе и идемпотентна при повторном запуске.

3. status сообщает о готовности разговоров, фактов и графа по отдельности.

Большие истории и локальное извлечение с поддержкой моделей могут занять несколько минут или дольше. Обычный режим переднего плана напрямую сообщает о завершении. Если вы выберете --background, «запущено» — это не «завершено»; продолжайте проверять memex status, пока количество ожидающих задач не достигнет ожидаемого состояния.

Установка из маркетплейса не изменяет исходные прогоны или производные данные до этого этапа первичной настройки. sync идемпотентна и безопасна для повторения.

Повседневное использование

memex sync
memex search "why did we choose SQLite?"
memex search --both "authentication migration"
memex stats
memex analyze --top 30 --out ~/memex-report.md
memex status

Инструменты MCP и навыки

Плагин предоставляет:

search, read, search_facts, search_ontology, ask_avatar,
trace_fact, explore_graph, cross_project_insights, graph_stats

Инструменты, чувствительные к проекту, требуют канонический абсолютный путь проекта или явную область действия global/all. Процесс MCP никогда не угадывает область действия по своему собственному cwd. Схемы и примеры см. в разделе MCP и навыки.

Локальный веб-интерфейс

npx --yes --package=github:BongSuCHOI/memex#main memex-ui
# http://localhost:3847

Маршруты:

• / — разговоры, проекты, поиск и обмены

• /facts — факты, ревизии, происхождение и защищённые изменения

• /graph — ограниченный по области действия живой 3D-граф знаний

• /pipeline — готовность и состояние отложенных задач

Сервер привязывается только к loopback. См. визуализацию.

Обновления

Просмотрите изменения, затем обновите снимок Git-маркетплейса и переустановите плагин:

memex update --dry-run
memex update

Лаунчер среды выполнения уже следует за последней версией main; memex update также обновляет снимок маркетплейса, поэтому обновлённые навыки, хуки и метаданные MCP устанавливаются вместе. После этого перезапустите Codex. Долговечные данные Memex сохраняются.

Происхождение извлечения и защита от самопоглощения

Memex записывает извлечения по хукам как долговечные квитанции memex_recall для каждого события, привязанные к сеансу и хэшу человеческого запроса. Результаты поиска Memex MCP классифицируются тем же способом. Происхождение определяется на уровне доказательств, а не на уровне ходов: человеческие утверждения и результаты из разрешённого списка — локального репозитория, Git-истории и выполнения тестов — остаются доступными для обучения даже рядом с извлечением; результаты Memex, вывод внешних/неизвестных инструментов и синтез, созданный ассистентом, — нет. Полный обмен остаётся доступным для поиска. Это предотвращает усиление цикла «извлечение → эхо агента → новый факт → извлечение», сохраняя при этом развитие фактов на основе доказательств.

Удаление

Хуки, управляемые плагином, исчезают при удалении плагина. Если более старая/ручная установка использовала setup-hooks, удалите только эти записи с отпечатками перед удалением плагина:

npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks --dry-run
npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks
codex plugin remove memex@memex --json
codex plugin marketplace remove memex --json

Удаление сохраняет и $CODEX_HOME/sessions, и производные данные Memex. Чтобы полностью удалить данные Memex, выполните memex home для определения точного корневого каталога данных, затем удалите этот каталог — никогда не трогайте $CODEX_HOME/sessions. Полное пошаговое руководство по удалению данных, включая варианты частичного сброса, см. в руководстве по эксплуатации.

Данные и конфиденциальность

Корневой каталог производных данных по умолчанию — ~/.config/memex. Порядок определения:

1. MEMEX_HOME

2. MEMORY_BANK_HOME (исторический, учитывается только для чтения)

3. MEMORY_BANK_CONFIG_DIR (исторический, учитывается только для чтения)

4. $XDG_CONFIG_HOME/memex

5. ~/.config/memex

Установки до версии 0.2, которые всё ещё хранят данные в историческом пространстве имён memory-bank, переносятся явно с помощью memex migrate-home (копирование → проверка → успех; исходный каталог никогда не удаляется). Это название — историческая совместимость хранилища, а не адаптер среды выполнения Claude. См. схему и границы безопасности.

Проверка

npm run typecheck
npm run build
npm test
npm run test:marketplace
npm run test:package
node --test test/codex-slice.test.mjs
node --test test/*slice.test.mjs
node scripts/validate-plugin.mjs

Codex CLI 0.149.1 не предоставляет codex plugin validate; репозиторий фиксирует эту границу версии и вместо неё запускает изолированную замену установленного артефакта. Текущие подтверждения и оставшиеся ограничения описаны в разделе проверка.

Участие в разработке

Клонируйте и собирайте только для разработки или участия:

git clone https://github.com/BongSuCHOI/memex.git
cd memex
npm ci
npm run build
npm test

Прочитайте AGENTS.md об инвариантах продукта, границах ответственности и обязательных проверках. При изменении поведения обновите документ владельца, указанный в карте документации, в том же изменении.

Лицензия

MIT. Атрибуция вышестоящего проекта и уведомления о сторонних компонентах находятся в docs/LINEAGE.md и THIRD_PARTY_NOTICES.md.