<p align="center">
<img src="https://raw.githubusercontent.com/julymetodiev/post-cortex/HEAD/design/v1.svg" width="128" height="128" alt="Post-Cortex Logo">
</p>
<h1 align="center">Post-Cortex</h1>
<p align="center"><strong>AI 어시스턴트를 위한 영구 메모리 (Persistent Memory for AI Assistants)</strong></p>
Post-Cortex는 AI 어시스턴트에게 장기 기억을 제공하는 MCP 서버입니다. 대화, 결정, 통찰력을 자동 개체 추출(automatic entity extraction) 기능을 통해 검색 가능한 지식 기반에 저장합니다.
기능 (Features)
-
영구 메모리 (Persistent Memory) — 세션 간에도 대화 내용이 유지됩니다.
-
시맨틱 검색 (Semantic Search) — 기본적으로 potion-multilingual-128M (Model2Vec)을 사용합니다. 디스크당 약 50 MB, 텍스트 추론 시 밀리초(ms)-per-text가 소요되며, 다국어(라틴/키릴/CJK/그리스/아랍어)를 즉시 지원합니다. 더 무거운 BERT 모델은 bert 기능을 통해 사용할 수 있습니다.
-
측정된 검색 (Measured retrieval) — 벡터 + BM25 검색을 RRF로 융합하고, 선택적으로 로컬 크로스 인코더(local cross-encoder) 또는 Voyage 리랭커(mode: fast / local / accurate)를 사용합니다. 각 검색 결과에는 주변 기록과 함께 반환됩니다. LoCoMo all@50: 0.793 / 0.878 / 0.936
-
그래프 RAG (Graph-RAG) — 개체 그래프 순회(entity-graph traversal) 및 관계 경로로 검색 결과가 풍부해집니다.
-
대화 기록 (Conversation capture) (선택 사항) — Claude Code hook을 사용하여 원본 턴(raw turns)을 세션별 메시지 스트림에 보관하며, 이는 기록과는 별도로 검색 가능합니다 (sources: records / messages / all); 기록은 자신이 파생된 턴(derived_from)과 연결될 수 있습니다.
-
카드 (Cards) — 워크스페이스당 짧고 버전이 지정된 프로젝트 카드와 모든 세션 앞에 표시되는 사용자 카드가 제공됩니다.
-
저작권(Authorship) — 기록과 메시지에는 누가 작성했는지 정보가 포함되며, 검색 시 저자별로 필터링하거나 특정 저자를 선호할 수 있습니다.
-
지식 그래프 (Knowledge Graph) — 모든 작성물은 유형화된 개체(entities) + 관계(relations)를 포함합니다 (0.3.0 버전부터 MCP 계약). 이 그래프는 텍스트와 동기화 상태를 유지합니다.
-
단일 진입점 아키텍처 (Single-entrypoint architecture) — 모든 전송 방식(gRPC, MCP, 향후 REST)은 동일한 표준 MemoryServiceImpl::update_context를 통해 라우팅됩니다. 따라서 드리프트할 수 있는 병렬 코드 경로가 없습니다.
-
영구적이고, 블로킹되지 않는 쓰기(Durable, non-blocking writes) — 쓰기는 스토리지 백엔드가 이를 인지했음(durable 응답)을 확인한 후에 반환됩니다. 임베딩 + 엔티티 그래프 병합 + 요약 새로고침은 제한된 배경 파이프라인에서 처리됩니다. 영구 데이터는 세션별로 통합되고 순서가 지정됩니다.
-
개인정보 비식별화(Redaction) — 자격 증명, 이메일 주소, 전화번호 및 공개 IPv4 주소는 저장되기 전에 모든 전송 과정에서 [REDACTED:<kind>]로 처리됩니다 (기본값으로 활성화; PC_REDACT=0 설정 시 비활성화).
-
인증 + 호스트 허용 목록(Auth + Host allowlist) — HTTP 및 gRPC에 선택적 베어러 토큰(PC_AUTH_TOKEN)이 사용됩니다. /mcp와 /api/* 경로는 알 수 없는 Host 헤더를 거부합니다 (DNS-재바인딩 보호, PC_ALLOWED_HOSTS).
-
개인정보 우선(Privacy-first) — 모든 처리는 로컬에서 실행됩니다 (임베딩 및 리랭커 모델은 첫 사용 시 Hugging Face에서 한 번 다운로드됨); 외부 API는 선택적 Voyage 리랭커뿐입니다.
-
락 프리 Rust 코어(Lock-free Rust core) — ArcSwap 세션 상태, 원자적 CAS 쓰기 경로를 사용합니다. 벡터 검색은 최대 10,000개 벡터까지 정확한 top-k 스캔이며, 그 이상은 HNSW를 사용하고, 세션별 인덱스를 가집니다.
-
유연한 스토리지(Flexible storage) — RocksDB (임베디드, 기본값) 또는 SurrealDB (로컬/원격, 분산형)
워크스페이스 레이아웃
이 레포지토리는 8개의 배포 가능한 크레이트(crate)를 가진 Cargo 워크스페이스입니다. 필요에 맞는 것을 선택하세요 — 페이시아드(post-cortex)가 모든 것을 가져오지만, 대부분의 소비자들은 일부 하위 집합만을 원합니다:
post-cortex-proto ──► post-cortex-core ──► post-cortex-storage ◄── post-cortex-embeddings
│ |
▼ |
...
A ──► B는 B가 A에 의존함을 의미합니다. post-cortex-embeddings는 다른 워크스페이스 크레이트에 의존하지 않습니다.
post-cortex-core는 저장소(storage), 머신러닝(ML) 또는 서버 의존성이 없습니다 (오직 tonic / prost만 post-cortex-proto를 통해 필요). 따라서 하위 Rust 프로젝트들은 RocksDB, Model2Vec / Candle 또는 서버 스택을 끌어들이지 않고도 타입 시스템만을 위해 이를 사용할 수 있습니다.
설치(Installation)
cargo install post-cortex-daemon --features "embeddings,surrealdb-storage"
...
라이브러리로 사용(As a library)
[dependencies]
post-cortex = "0.5"
...
빠른 시작(Quick Start)
1. MCP 구성 (최초, 전역 설정)
claude mcp add --scope user --transport http post-cortex http://127.0.0.1:3737/mcp \
--header "X-PCX-Author: claude-code"
...
X-PCX-Author / PC_AUTHOR는 쓰기 작업 시 기록의 출처를 지정하지 않은 경우 해당 기록이 어디에서 왔는지 알려줍니다. MCP 클라이언트는 종종 자신의 SDK 이름만 보고합니다.
이를 통해 Post-Cortex가 사용자의 모든 프로젝트에 등록됩니다.
2. 프로젝트 설정(Set Up Your Project)
이 명령어는 세션, 작업 공간(workspace), 메모리 규칙을 담은 CLAUDE.md, 후크(Stop 시 로그 확인, SessionStart 시 카드 확인) 및 post-cortex-memory 스킬을 생성합니다. pcx setup --capture는 대화 캡처 후크도 설치하며; --daemon-url / --capture-url은 해당 후크를 다른 호스트의 데몬으로 지정합니다. 자세한 내용은 **사용 가이드**를 참조하십시오.
3. 코딩 시작(Start Coding)
Claude는 답변하기 전에 자동으로 과거 지식을 검색하고 새로운 발견을 기록합니다.
아홉 가지 도구:
| Tool | 목적 |
|---|
session | 세션 생성 / 목록 보기 / 로드 / 검색 / 메타데이터 업데이트 / 세션 삭제 |
| ... | |
데몬 모드(Daemon Mode)
여러 Claude 인스턴스가 동일한 메모리를 공유하는 경우:
pcx start
pcx status
pcx stop
Claude를 HTTP 전송 방식으로 구성합니다:
{
"mcpServers": {
"post-cortex": {
...
자세한 내용은 [Daemon Mode docs]에서 확인하세요.
데이터 내보내기/가져오기 (Data Export/Import)
pcx export --output backup.json
pcx export --output backup.json.gz
pcx import --input backup.json
스토리지 백엔드 (Storage Backends)
| RocksDB (기본값) | SurrealDB |
|---|
| 설정 | 별도 구성 불필요 (Zero config) | 서버 필요 (Requires server) |
| ... | | |
~/.post-cortex/daemon.toml에서 구성하세요. [Daemon Mode docs]를 참조하세요. | | |
환경 변수 (Environment Variables)
| 변수명 | 기본값 | 설명 |
|---|
PC_HOST | 127.0.0.1 | 바인딩 주소 (Bind address) |
| ... | | |
개발 (Development)
cargo build --release --features "embeddings,surrealdb-storage"
...
공급망 위생 (Supply-chain hygiene)
cargo fmt --all --checkcargo clippy --workspace --all-targets --all-features -- -D warningscargo deny check — [deny.toml] 참조cargo audit — [.cargo/audit.toml] 참조
CI는 main 브랜치에 푸시할 때 네 가지 모두를 강제합니다.
릴리스 노트 (Release notes)
현재 릴리스 버전은 0.5.0입니다. 이 버전에는 측정된 검색 파이프라인(BM25, rerankers, 검색 모드, 이웃), 대화 기록, 프로젝트 및 사용자 카드, 레코드와 메시지에 대한 저자 정보가 포함되었습니다.
업그레이드 전:
- SurrealDB: 데이터베이스를 먼저 백업하세요. 데몬이 시작될 때 전체 텍스트 인덱스와 메시지 및 카드 테이블을 추가합니다.
- RocksDB: 이전 데이터는 그대로 로드됩니다. 0.5.0으로 작성된 데이터는 이전 바이너리에서 읽을 수 없습니다.
- Linux의 로컬 reranker: ONNX Runtime 1.31을 설치하고
ORT_DYLIB_PATH를 libonnxruntime.so로 설정하세요. reranker_model이 설정되고 search_mode가 없으면 검색은 기본적으로 local(~1초)에 머무릅니다. 이전 지연 시간을 유지하려면 `search_mode =
MIT — see LICENSE.
