Memex

흩어진 Codex 대화를 수집하고, 지속 가능한 지식을 증류하며, 연결하고, 색인하여, 필요할 때 올바른 기억을 다시 가져옵니다.

Memex는 Codex를 위한 로컬 우선 개인 지식 시스템입니다. 로컬 롤아웃 세션을 검색 가능한 대화 아카이브, 지속 가능한 사실, 온톨로지 기반 지식 그래프, 그리고 Codex가 이후 작업에서 재사용할 수 있는 경계 있는 컨텍스트로 전환합니다.

한국어 README · 문서 · 설치 및 운영 · 아키텍처 · 스키마

Memex는 MIT 라이선스의 jung-wan-kim/memory-bank에서 파생된 독립적인 Codex 네이티브 프로젝트이며, 이는 obra/episodic-memory에서 유래했습니다. 지식 시스템 기능은 유지하되 Claude Code 호환 코드는 포함하지 않습니다. 계보 및 마이그레이션을 참조하세요.

왜 0.1.0인가?

0.1.0은 적절한 첫 공개 릴리스입니다. 기능 세트는 상당하고 테스트되었지만, 저장소는 새로 독립했으며 Codex 마켓플레이스, 호스트 어댑터, 설치 계약은 안정적인 1.0.0 이전에 변경될 수 있습니다. 버전 1.0.0은 이러한 공개 계약이 의도적으로 안정적임을 의미하며, 단지 많은 기능이 존재한다는 뜻이 아닙니다.

Related MCP server: codex-memory-mcp

기능

• Codex 대화 기록에 대한 의미론적, FTS5/BM25, 하이브리드 검색

• LLM 호출 없이 결정적 전체 기록 분석

• 증분 사실 추출, 신뢰도 게이트, 통합, 수정, 출처 추적

• 도메인/카테고리 온톨로지 및 유형화된 지식 그래프 관계

• 프로젝트, 전역, 명시적으로 요청된 전체 프로젝트 범위 격리

• 1~3홉 그래프 탐색 및 교차 프로젝트 인사이트

• 관련성 및 세션별 중복 제거를 포함한 경계 있는 RAG 컨텍스트 주입

• 압축된 .jsonl.zst 아카이브에 대한 투명한 경계 읽기

• 대화, 사실, 온톨로지, 그래프, 출처를 위한 9가지 MCP 도구

• 회상, 기록 분석, 대시보드 워크플로를 위한 3가지 Codex 스킬

• 사실, 파이프라인 상태, 3D Knowledge Galaxy를 갖춘 루프백 전용 웹 UI

• 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 및 스킬

• 웹 UI 및 3D 시각화

요구 사항

• Node.js 22.15 이상

• 인증된 Codex CLI

• 현재 훅 및 Unix 소켓 런타임을 위한 macOS 또는 Linux

플러그인은 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 서버, 스킬, 플러그인 관리 훅이 새 세션에 로드되도록 합니다.

읽기 쉬운 터미널 명령을 위해 세션 로컬 셸 함수를 정의하세요. 항상 최신 main 런타임을 대상으로 하며 전역 설치하지 않습니다:

memex() { npx --yes --package=github:BongSuCHOI/memex#main memex "$@"; }

그런 다음 일회성 코퍼스 설정을 수행합니다:

memex setup
memex sync
memex backfill extract --foreground
memex backfill ontology --foreground
memex backfill embeddings --foreground
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 extract는 이미 색인된 교환에서 지속 가능한 사실을 증류합니다.

3. backfill ontology는 사실을 분류하고 그래프 구조를 구축합니다.

4. backfill embeddings는 누락된 의미 벡터를 채웁니다.

5. 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 및 스킬을 참조하세요.

로컬 웹 UI

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

경로:

• / — 대화, 프로젝트, 검색, 교환

• /facts — 사실, 수정, 출처, 보호된 변경

• /graph — 범위 지정 실시간 3D 지식 그래프

• /pipeline — 준비 상태 및 백로그 상태

서버는 루프백에만 바인딩됩니다. 시각화를 참조하세요.

업데이트

미리 본 다음 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의 파생 데이터를 모두 보존합니다. 수동으로 삭제하기 전에 정확한 데이터 경로를 검토하세요. 운영 가이드를 참조하세요.

데이터 및 개인정보 보호

기본 파생 데이터는 지속 데이터 호환성을 위해 ~/.config/memory-bank에 유지됩니다. 해석 순서:

1. MEMORY_BANK_HOME

2. MEMORY_BANK_CONFIG_DIR

3. $XDG_CONFIG_HOME/memory-bank

4. ~/.config/memory-bank

이름은 역사적 저장소 호환성일 뿐 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에 있습니다.