Skip to main content
Glama
Sign In
deenesjakoruzh
ctx-memory

ctx-memory

by GhadiSaab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ctx-memory

LLM 코딩 에이전트(Claude Code, Codex, Gemini CLI, OpenCode)를 위한 영구 메모리입니다.

새 세션을 시작할 때 에이전트는 이미 지난번에 작업한 내용(내린 결정, 수정한 파일, 발생한 오류, 학습한 규칙 등)을 알고 있습니다. 클라우드도 없고, 텔레메트리도 없습니다. 모든 데이터는 ~/.ctx-memory/store.db의 로컬 SQLite 데이터베이스에 저장됩니다.

작동 방식

Session starts
      │
 Shell wrapper intercepts 'claude' (or codex/gemini/opencode)
      │
 MCP server starts alongside — injects prior context, exposes memory tools
      │
 During session: hooks fire on every tool call, messages buffered
      │
 Session ends (clean exit / Ctrl-C / crash)
      │
 Layer 1 → Layer 2 → Layer 3 pipeline runs
      │
      ├── Layer 1: extract weighted messages, events, decisions, errors, keywords
      ├── Layer 2: compress to ≤500-token digest, store in DB
      └── Layer 3: merge digest into project memory doc (markdown)

Next session: agent reads prior context automatically

Related MCP server: remem

설치

npm install -g ctx-memory
ctx-memory setup

설정 마법사:

  1. 설치된 도구(claude, codex, gemini, opencode)를 감지합니다.

  2. 통합할 도구를 선택하라는 메시지를 표시합니다.

  3. 각 도구에 대한 후크 설정을 작성합니다.

  4. ~/.ctx-memory/bin/에 래퍼 심볼릭 링크를 생성합니다.

  5. ~/.bashrc / ~/.zshrc를 통해 ~/.ctx-memory/bin을 PATH에 추가합니다.

셸을 다시 시작하거나 source ~/.bashrc를 실행한 후, 평소처럼 도구를 사용하세요. 메모리는 자동으로 관리됩니다.

명령어

ctx-memory setup                        # interactive setup wizard
ctx-memory status                       # show configuration and stats
ctx-memory projects list                # list all projects
ctx-memory projects show <name>         # print full memory doc for a project
ctx-memory projects forget <name>       # reset memory (keeps sessions)
ctx-memory projects forget <name> --hard  # delete all sessions + data

MCP 서버

MCP 서버는 각 도구 세션과 함께 사이드카로 실행되며 6가지 도구를 제공합니다.

도구

설명

store_message

세션 종료 시 처리를 위해 대화 메시지를 버퍼링합니다

store_event

도구 호출 이벤트(파일 편집, bash 명령 등)를 기록합니다

search_context

의미론적 유사성 또는 키워드로 과거 세션을 검색합니다

get_project_memory

전체 프로젝트 메모리 문서를 반환합니다

list_sessions

목표와 결과가 포함된 최근 세션 목록을 표시합니다

end_session

세션을 마무리하고 1단계 → 2단계 → 3단계 파이프라인을 실행합니다

Claude Code와 함께 MCP 서버를 독립적으로 사용하려면 ~/.claude/settings.json에 다음을 추가하세요:

{
  "mcpServers": {
    "ctx-memory": {
      "command": "node",
      "args": ["/path/to/ctx-memory/dist/src/mcp/index.js"]
    }
  }
}

아키텍처

src/
  cli/        — setup wizard, status, projects commands
  db/         — SQLite schema + CRUD (projects, sessions, events, digests, memory)
  layer1/     — pure message/event processing → weighted Layer1Output
  layer2/     — digest compression to ≤500 tokens → Layer2Digest
  layer3/     — merge digest into ProjectMemory markdown
  mcp/        — MCP server (handlers + stdio entry point)
  wrapper/    — shell wrapper (intercepts tool invocation, manages session lifecycle)
  hooks/      — hook config writers for Claude / Gemini / OpenCode

주요 제약 사항:

  • 모든 1/2/3단계 함수는 순수 함수입니다(I/O 없음, 예외 발생 없음).

  • 요약은 500토큰 미만으로 유지됩니다.

  • 벡터 검색은 sqlite-vec(384차원)을 통해 all-MiniLM-L6-v2 임베딩을 사용합니다.

  • 단일 SQLite DB, WAL 모드, 외래 키 활성화.

개발

npm run build       # tsc → dist/
npm run dev         # tsc --watch
npm run test:run    # vitest (single-shot, 476+ tests)
npm test            # vitest (watch mode)

DB 경로는 기본적으로 ~/.ctx-memory/store.db입니다. CTX_MEMORY_DB_PATH로 재정의할 수 있습니다.

라이선스

MIT

Available Tools

6 tools
end_sessionC

Signal session end — runs Layer 1→2→3 pipeline, stores digest, updates project memory.

Inputs: outcome (required), project_id (required), session_id (required), exit_code.

get_project_memoryC

Return the full project memory document (architecture, conventions, recent work, known issues).

Inputs: project_id.

list_sessionsC

List recent sessions for a project with their goals and outcomes.

Inputs: limit, project_id.

search_contextB

Search past sessions for context relevant to a query. Uses embedding similarity, falls back to keyword search.

Inputs: query (required), limit, project_id.

store_eventC

Record a tool call event (file edit, bash command, etc.) for the current session.

Inputs: tool (required), session_id (required), args, result, +1 more.

store_messageC

Buffer a conversation message for session-end processing.

Inputs: role (required), index (required), content (required), session_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: session lifecycle (end_session), memory retrieval (get_project_memory, list_sessions, search_context), and data recording (store_event, store_message). No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, e.g., end_session, get_project_memory, store_event. The naming is predictable and uniform.

    Tool Count5/5

    With 6 tools, the server covers core memory management operations without bloat. The count is well-scoped for the domain of session context and project memory.

    Completeness5/5

    The tool surface covers the full typical lifecycle: recording events/messages, searching and retrieving context, listing sessions, and finalizing sessions with memory updates. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers