전체 문서 -- 가이드, 도구 참조, 아키텍처 및 유지 관리에 대한 내용은 cachorro.space에서 확인하세요.

mcp-memory

Anthropic의 MCP 메모리 서버를 위한 드롭인 대체제입니다. SQLite 지속성, 벡터 임베딩, 의미론적 검색, 그리고 동적 순위 지정을 위한 Limbic Scoring 기능을 제공합니다.

왜 필요한가요? 기존 서버는 모든 작업 시 전체 지식 그래프를 JSONL 파일에 기록하며, 잠금이나 원자적 쓰기 기능이 없습니다. 동시 접근(여러 MCP 클라이언트) 환경에서는 데이터 손상이 발생합니다. 이 서버는 이를 적절한 SQLite 데이터베이스로 대체합니다.

주요 기능

• 드롭인 호환 -- Anthropic의 8개 MCP 도구와 동일한 API 및 동작

• SQLite + WAL -- 안전한 동시 접근, 더 이상 손상되지 않는 JSONL

• 의미론적 검색 -- sqlite-vec + ONNX 임베딩을 통한 검색 (94개 이상의 언어 지원)

• 하이브리드 검색 (FTS5 + KNN) -- BM25 전체 텍스트 검색과 의미론적 벡터 검색을 Reciprocal Rank Fusion으로 결합. 정확한 용어나 의미론적 유사성, 또는 둘 다를 사용하여 엔티티를 찾습니다.

• Limbic Scoring -- 중요도, 시간적 감쇠, 동시 발생 신호 및 하이브리드 검색 점수를 사용한 동적 재순위 지정. API에 투명하게 작동합니다.

• 의미론적 중복 제거 -- 코사인 유사도가 0.85 이상일 때 새로운 관찰에 대한 자동 similarity_flag (비대칭 텍스트 길이에 대한 포함 점수 포함)

• 통합 보고서 -- 분할 후보, 플래그 지정된 관찰, 오래된 엔티티 및 대형 엔티티에 대한 읽기 전용 상태 점검

• 향상된 최신성 감쇠 -- ALPHA_CONS=0.2 다일 통합 신호를 포함한 entity_access_log 추적

• 포함 수정 -- 중복 제거 점수 산정 시 비대칭 텍스트 길이(비율 >= 2.0)에 대한 적절한 처리

• 관찰 종류 -- 관찰의 의미론적 분류 (hallazgo, decision, estado, spec, metrica, metadata, generic)

• 관찰 대체 -- 명시적 교체 체인: 새로운 관찰이 이전 관찰을 대체할 수 있으며, 이전 관찰은 대체된 것으로 타임스탬프가 찍힙니다.

• 엔티티 상태 -- 수명 주기 추적: activo, pausado, completado, archivado (상태 인식 검색 디부스팅 포함)

• 관계 컨텍스트 + 유효 기간 -- 관계는 선택적 컨텍스트, active/ended_at 필드를 포함하여 시간적 유효성을 가집니다.

• 자동 역관계 -- contains/parte_de 쌍이 자동으로 생성됩니다.

• 성찰(Reflections) -- 독립적인 서사 계층: 엔티티/세션/관계/전역에 첨부된 자유 형식의 산문, 작성자 및 분위기 메타데이터 포함, 의미론적 + FTS5 하이브리드 검색 가능

• 경량화 -- 유사 솔루션의 약 1.4GB 대비 총 약 500MB

• 마이그레이션 -- Anthropic의 JSONL 형식에서 원클릭 가져오기

• 제로 설정 -- 즉시 사용 가능, 의미론적 검색을 위한 선택적 모델 다운로드

빠른 시작

1. MCP 설정에 추가

{
  "mcpServers": {
    "memory": {
      "command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

또는 로컬에서 복제 및 실행:

{
  "mcpServers": {
    "memory": {
      "command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
    }
  }
}

2. 의미론적 검색 활성화 (선택 사항)

cd /path/to/mcp-memory
uv run python scripts/download_model.py

이 작업은 다국어 문장 모델(~465MB)을 ~/.cache/mcp-memory-v2/models/로 다운로드합니다. 이 모델이 없어도 모든 도구는 정상 작동하지만 search_semantic은 사용할 수 없습니다.

3. 기존 데이터 마이그레이션 (선택 사항)

Anthropic MCP 메모리 JSONL 파일이 있는 경우 migrate 도구를 사용하거나 직접 호출하세요:

uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"

MCP 도구

핵심 (Anthropic 호환)

검색 및 분석

엔티티 관리

성찰(Reflections)

엔티티 유형

8가지 표준 유형:

관찰 종류

관찰에 대한 의미론적 분류:

관계 유형

4가지 범주:

contiene/parte_de 쌍에 대해서는 역관계가 자동으로 생성됩니다.

아키텍처

server.py (FastMCP)  <--  storage.py (SQLite + sqlite-vec + FTS5)
                               |
                         embeddings.py (ONNX Runtime)
                               |
                         sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
                         (384d, multilingual, cosine similarity)
                               |
                         scoring.py (Limbic Scoring + RRF)
                         salience . temporal decay . co-occurrence

• 저장소: WAL 저널링이 포함된 SQLite, 5초 바쁜 타임아웃, CASCADE 삭제

• 임베딩: 시작 시 한 번 로드되는 싱글톤 ONNX 모델, L2 정규화된 코사인 검색

• Limbic Scoring: 중요도 신호, 시간적 감쇠, 동시 발생 패턴 및 RRF 점수를 사용하여 하이브리드(KNN + FTS5) 후보를 재순위 지정 -- API에 투명함

• 동시성: SQLite가 내부적으로 잠금 처리 -- fcntl 없음, fs 전쟁 없음

• 성찰: 서사 계층을 위한 병렬 FTS5(reflection_fts) 및 벡터(reflection_embeddings) 인덱스, 동일한 RRF 하이브리드 파이프라인을 통해 검색

작동 원리

각 엔티티는 Head+Tail+Diversity 선택 전략(예산: 480 토큰)을 사용하여 텍스트에서 생성된 임베딩 벡터를 가집니다:

"{name} ({entity_type}) | {obs1} | {obs2} | ... | Rel: type -> target; ..."

search_semantic을 호출하면 파이프라인이 병렬로 실행됩니다:

1. 의미론적 (KNN) -- 쿼리가 인코딩되고 sqlite-vec을 통해 엔티티 벡터와 비교됩니다.

2. 전체 텍스트 (FTS5) -- 쿼리가 이름, 유형 및 관찰 내용을 다루는 BM25 인덱스에 대해 검색됩니다.

3. 병합 (RRF) -- 두 분기의 결과가 Reciprocal Rank Fusion(score(d) = Sum 1/(k + rank))을 사용하여 결합됩니다.

병합된 후보는 다음을 고려하는 Limbic Scoring 엔진에 의해 재순위 지정됩니다:

• 중요도(Salience) -- 자주 액세스되고 잘 연결된 엔티티가 더 높은 순위를 차지합니다.

• 시간적 감쇠 -- 최근 사용된 엔티티는 신선하게 유지되고, 사용되지 않은 엔티티는 희미해집니다.

• 동시 발생 -- 자주 함께 나타나는 엔티티는 서로를 강화합니다.

출력에는 limbic_score, scoring(중요도/시간적/동시 발생 분석), 그리고 FTS5가 결과를 기여할 때 선택적으로 rrf_score가 포함됩니다.

전체 기술 세부 정보는 DOCUMENTATION.md를 참조하세요. 여기에는 점수 산정 공식, RRF 상수, 스키마 DDL 및 아키텍처 다이어그램이 포함되어 있습니다.

테스트

uv run pytest tests/ -v

모든 도구, 임베딩, 점수 산정 및 엣지 케이스를 다루는 15개 테스트 파일에 걸쳐 285개 이상의 테스트가 수행되었습니다. 회귀 오류는 없습니다.

요구 사항

• Python >= 3.12

• uv (패키지 관리자)

종속성

라이선스

MIT