Cortex

문제

코딩 에이전트가 화요일에 골칫거리 버그를 해결합니다. 그런데 수요일이 되면 새 컨텍스트 창을 열지만, 그런 버그가 있었는지조차 알지 못합니다. 그래서 같은 설명을 다시 붙여넣게 됩니다.

Cortex는 에이전트가 MCP를 통해 스스로 쓰고 읽는 메모리를 제공합니다: 구조화된 기억(bug_fix, decision, discovery, pattern, preference, ...)을 프로젝트 단위로 범위를 정하고, 관련성에 따라 순위를 매기고, 시간이 지나면 감쇠시키며, 같은 증상이 다시 나타나면 다시 떠오르게 합니다.

모든 것은 사용자 컴퓨터의 단일 SQLite 파일(~/.memoria/memoria.db)에 저장됩니다. 계정도, API 키도, 텔레메트리도 없습니다.

Related MCP server: exocortex

제공되는 것

• 20가지 MCP 도구 — 저장 / 검색 / 컨텍스트 / 회상 / 힌트 / 피드백 / 세션 / 성찰 / 잊기 (전체 목록).

• 하이브리드 검색 — Reciprocal Rank Fusion(RRF)으로 융합된 SQLite FTS5 전체 텍스트 검색과 벡터 KNN을 함께 사용합니다. 임베딩은 선택 사항이며 로컬에서 실행됩니다(@xenova/transformers, 384차원 MiniLM, 약 22MB, CPU).

• 결과 기반 신뢰도 — 에이전트가 떠오른 기억이 도움이 되었는지, 오래되었는지, 오해를 불러일으켰는지를 보고합니다(memoria_feedback); 신뢰 점수는 이후 결과의 순위를 다시 매깁니다.

• 선제적 힌트 — memoria_hint가 다가올 도구 호출, 프롬프트, 파일 경로를 받아 실행 전에 주입할 짧은 힌트를 최대 3개 돌려줍니다.

• 성찰(Reflections) — CPU 전용 클러스터링 패스가 관련 기억을 묶고, 에이전트의 LLM이 메타 교훈을 종합합니다(Cortex는 절대 스스로 LLM을 호출하지 않습니다).

• 감쇠 및 망각 — 시간이 지나면 관련성이 감쇠하고, memoria_forget은 미리보기를 제공하며(기본은 dry-run) 임계값 아래의 기억을 소프트 삭제합니다.

• 기본 제공되는 프라이버시 — API 키, PAT, JWT, SSH 키, <private>...</private> 블록은 무엇이든 디스크에 기록되기 전에 제거됩니다.

• 운영 준비 완료 — 구조화된 JSON 로그, /api/metrics의 Prometheus 메트릭, 할당량, 선택적 bearer 인증, 멀티테넌트 워크스페이스를 제공합니다.

빠른 시작 (2분)

요구 사항: Node >= 20 (22, 26에서 확인), git. better-sqlite3은 설치할 때 컴파일하거나 미리 빌드된 바이너리를 내려받습니다. 그 외 시스템 의존성은 없습니다.

git clone https://github.com/gonzalonicolasr/cortexmem.git
cd cortexmem
npm install
npm test          # optional: 216 tests, ~1s

또는 클론하지 않고도 설치할 수 있습니다. 그러면 PATH에 cortexmem 명령이 생깁니다:

npm install -g github:gonzalonicolasr/cortexmem
cortexmem --version

일반 CLI처럼 스모크 테스트를 해보세요:

node bin/memoria.mjs save "Fix hydration bug" \
  --type bug_fix --what "moved the fetch out of useEffect" \
  --project demo --learned "SSR/CSR mismatch, not a race condition"

node bin/memoria.mjs search hydration --project demo
node bin/memoria.mjs stats

끝입니다 — 데이터베이스는 처음 쓰기(write)가 하는 시점에 ~/.memoria/memoria.db에 생성됩니다.

에이전트에 연결하기

Cortex는 stdio 위에서 MCP를 사용합니다. 전역으로 설치했다면 명령은 cortexmem mcp이고, 클론한 저장소를 사용한다면 bin/memoria.mjs의 절대 경로를 지정해 node를 실행하세요.

claude mcp add cortex -- node /absolute/path/to/cortexmem/bin/memoria.mjs mcp
claude mcp list | grep cortex     # → ✓ Connected

[mcp_servers.cortex]
command = "node"
args = ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]

{
  "mcpServers": {
    "cortex": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]
    }
  }
}

pi용 MCP 확장을 설치하고, 위 JSON 예제와 같은 명령/인자 조합을 지정하세요. HTTP 전송 방식은 docs/self-hosting.md를 참고하세요.

설정을 편집한 뒤에는 클라이언트를 재시작하세요 — Codex와 Claude Code는 설정을 실시간으로 다시 읽지 않습니다.

에이전트가 실제로 사용하도록 지도하기

도구만으로는 부족합니다. 에이전트가 언제 저장해야 하는지를 알아야 합니다. CLAUDE.md(메모리 프로토콜)을 에이전의 지시 파일(CLAUDE.md, AGENTS.md, .cursorrules, pi의 AGENTS.md, ...)에 복사하세요. 약 40줄이며, 에이전트에게 버그 수정, 결정, 발견, 설정 변경 후 자동으로 저장하고 세션 시작 시 memoria_context를 호출하도록 지시합니다.

CLI

memoria mcp                    Start the MCP server (stdio)
memoria serve [port]           Start the HTTP API (default 7437, loopback-only)
memoria save <title> [flags]   Save a memory
memoria search <query>         Full-text search
memoria context [project]      Print the project context block
memoria recent [flags]         Recent memories
memoria stats                  Counts by type / project
memoria projects               List projects
memoria decay                  Apply relevance decay

플래그: --project --type --limit --what --why --where --learned --topic.

서버 모드

홈랩의 모든 머신/에이전트가 하나의 메모리를 공유하길 원하나요? HTTP API를 실행하고 앞단에 리버스 프록시를 두세요:

MEMORIA_HOST=127.0.0.1 MEMORIA_AUTH_TOKEN=$(openssl rand -hex 24) \
  node bin/memoria.mjs serve 7437
curl -s localhost:7437/api/health

엔드포인트 참고: docs/http-api.md. systemd 유닛, Bearer 인증, 임베딩 백필, reflection 크론과 백업은 docs/self-hosting.md를 참고하세요.

⚠️ HTTP 서버는 X-Workspace-Id 헤더를 신뢰합니다(멀티테넌트 설계: 상위 프록시가 사용자를 검증해 이 헤더를 주입합니다). MEMORIA_AUTH_TOKEN과 앞단 프록시 없이 공인 인터페이스에 바인딩하지 마세요.

시맨틱 검색(선택 사항)

npm install @xenova/transformers          # already an optionalDependency
export MEMORIA_SEMANTIC_SEARCH=1
node bin/backfill-embeddings.mjs          # embed existing memories

모델은 한 번 다운로드하면(약 22MB이며 CPU에서 실행됩니다. 플래그가 켜져 있으면 memoria_search와 memoria_recall은 하이브리드(FTS5 + KNN을 RRF로 융합)가 됩니다. 꺼두면 모든 것이 순수 키워드 검색으로도 동작합니다. 영어가 아닌 메모리는 백필 이전에 MEMORIA_EMBEDDING_MODEL=Xenova/paraphrase-multilingual-MiniLM-L12-v2로 설정하세요(동일한 384차원) — 시맨틱 검색 참고.

환경 변수

Quotas

기본값은 멀티테넌티드 호스팅 운영을 위한 것입니다: 활성 메모리 1,000개, 논리 텍스트 10MB, 프로젝트 50개, 활성 세션 5개, 메모리당 32KB. 개인 로컬 설치는 그 한도를 더 높여도 좋습니다:

export MEMORIA_UNLIMITED_WORKSPACES=1   # workspace 1 = the CLI/stdio default

MCP 도구

도구 이름에는 기존 설치와 하위 호환성을 유지하기 위해 프로젝트의 원래 이름인 memoria_ 접두사가 붙어 있습니다.

데이터, 프라이버시, 백업

• 하나의 SQLite 파일(WAL 모드). sqlite3 ~/.memoria/memoria.db ".backup out.db"로 백업하세요.

• 비밀정보는 행 기록 이전에 모두 날아갑니다: AWS keys, GitHub/GitLab PAT, JWT, SSH 개인 키, 그리고 <private>...</private>로 감싼 어떤 것도 제거됩니다. 이것은 안전망이지, 비밀번호를 그대로 붙여넣어도 된다는 것은 아닙니다.

• 어떤 것도 PC 밖으로 나가지 있습니다. 당신이 HTTP 서버를 실행해 외부로 직접 노출하지 않는 한입니다.

개발

npm test          # vitest, 216 tests
npm run test:watch

멀티언어 임베딩 테스트는 MEMORIA_TEST_MULTILINGUAL=1일 때만 실행되므로 일반 테스트 스위트가 객체를 내려받지 않습니다. 변경 내역: CHANGELOG.md.

호스팅 (선택 사항)

다른 방법으로는 아무것도 직접 운영하고 싶지 않을 때, 동일한 엔진을 cortexmem.com에서 호스팅해 드립니다: 깃허브 로그인, 패널의 cc_... API 키 복사, 그리고 로컬 명령 대신 HTTP endpoint를 클라이언트가 사용하도록 설정합니다:

claude mcp add cortex https://cortexmem.com/api/cortex/mcp \
  --transport http --header "Authorization: Bearer cc_YOUR_KEY"

# ~/.codex/config.toml
[mcp_servers.cortex]
url = "https://cortexmem.com/api/cortex/mcp"

[mcp_servers.cortex.http_headers]
Authorization = "Bearer cc_YOUR_KEY"

셀프 호스팅은 모든 기능이 그대로 제공되며, 호스팅 티어는 메모리 자체가 아니라 웹 패널과 브레인 그래프를 추가로 제공합니다.

라이선스

MIT © Gonzalo Rocca — LICENSE 참조.