MCP-Memory: OKF 및 SQLite FTS5를 활용한 빠른 에이전트 메모리

Quick Take

MCP-Memory는 AI 에이전트에게 로컬 SQLite FTS5 데이터베이스에 인덱싱된 OKF‑v0.2 준수 지속성 메모리를 제공하여, 사람이 브라우징 가능한 마크다운 디렉토리를 유지하면서도 20ms 미만의 키 조회와 즉각적인 전체 텍스트 검색을 실현합니다.

MCP-Memory란 무엇인가

MCP-Memory는 Claude Desktop, Cursor, Antigravity, Windsurf 또는 Codex와 같은 에이전트에게 장기적이고 검색 가능한 메모리를 제공하는 Model Context Protocol (MCP) 서버입니다. 각 메모리 레코드는 풍부한 YAML front-matter를 포함한 OKF v0.2 마크다운 문서로 저장되며, 동일한 데이터는 빠른 검색을 위해 SQLite FTS5에 인덱싱됩니다.

핵심 설계 선택

이중 레이어 아키텍처

  • 사람이 브라우징 가능한 OKF 디렉토리 – 모든 메모리는 계층적 index.md 파일을 가진 .md 파일 형태로 memory/에 저장되어, 버전 관리가 가능하고 읽기 쉬운 지식 베이스를 제공합니다.
  • 고성능 SQLite 인덱스 – FTS5 트리거가 포함된 SQLite 데이터베이스를 통해 20ms 미만의 키-값 조회를 지원하며, 키, front-matter 및 콘텐츠 전반에 걸친 키워드 검색이 가능합니다.

네임스페이스 격리

메모리는 네임스페이스(예: user/preferences, project/architecture, default)별로 분할할 수 있어 프로젝트 간 데이터 혼선을 방지합니다.

제로 보일러플레이트 설정

python3 setup.py를 실행하면 지원되는 에이전트를 자동으로 감지하고 memory MCP 서버를 등록하므로, 에이전트가 영구적인 터미널 프로세스 없이도 자동으로 서버를 실행합니다.

에이전트에게 제공되는 MCP 도구

도구 목적 주요 매개변수
memory_store 메모리 레코드 생성 또는 업데이트 key, content, project_root, 선택적 tags, namespace, concept_type, title, description, resource, status, stale_after, sources, verified, generated_by
memory_retrieve 키를 통해 단일 레코드 가져오기 key, project_root, 선택적 namespace
memory_search 전체 텍스트 또는 태그 기반 검색 project_root, 선택적 query, tags, namespace, limit
memory_get_last 시작 시 세션 체크포인트(system/last_memory) 가져오기 project_root, 선택적 namespace
memory_update_last 마일스톤 달성 후 체크포인트 업데이트 content, project_root, 선택적 namespace, summary

실제 OKF v0.2 사양 적용

각 메모리는 다음과 같이 OKF front-matter 스키마를 따릅니다:

---
type: Agent Memory
title: Coding Style
key: user/preferences/coding_style
namespace: default
tags:
  - preferences
  - style
status: stable
generated:
  by: mcp-memory/0.2.0
  at: '2026-08-12T19:23:35Z'
created_at: '2026-08-12T19:23:35Z'
updated_at: '2026-08-12T19:23:35Z'
---
User prefers functional programming style with explicit type annotations.

동일한 파일이 memory/에 저장되는 동시에, 검색 가능한 표현은 .mcp_memory/memories.db에 저장됩니다.

설치 및 빠른 시작

  1. 저장소 클론:
    git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory
  2. 설정 마법사 실행을 통해 지원되는 에이전트에 서버를 자동 등록합니다:
    python3 setup.py
    완료 후 에이전트가 필요 시 mcp-memory를 실행합니다.
  3. 디버깅을 위한 선택적 수동 시작:
    /run.sh

수동 클라이언트 설정

명시적인 설정을 선호하는 경우, run.sh를 가리키는 memory 항목을 추가합니다:

JSON (Antigravity, Claude Desktop, Cursor, Windsurf)

{
  "mcpServers": {
    "memory": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

TOML (Codex Desktop)

[mcp_servers.memory]
command = "/ABSOLUTE/PATH/TO/run.sh"

CLI 예시

claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh

저장소 레이아웃 및 환경 변수

  • OKF 마크다운 – 프로젝트 루트 내부의 memory/ 디렉토리.
  • SQLite 인덱스 – .mcp_memory/memories.db (숨김).
  • 환경 변수를 통해 사용자 지정 위치를 지정할 수 있습니다:
    • MCP_MEMORY_PROJECT_ROOT – 기본값은 현재 작업 디렉토리.
    • MCP_MEMORY_DB_PATH – 기본값은 .mcp_memory/memories.db.
    • MCP_MEMORY_DIR – 기본값은 memory.
  • 여러 프로젝트에서 단일 저장소를 공유하려면 MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db 및 MCP_MEMORY_DIR=~/.mcp_memory/memory로 설정하십시오.

커뮤니티 피드백 하이라이트

@myshapeprotocol – “빠른 에이전트 메모리를 위해 SQLite FTS5를 사용하는 것은 매우 실용적인 아키텍처 선택입니다. 훌륭한 Show HN 프로젝트네요.”

@bearjaws – “또 한 주가 지나갔고, memory/ 디렉토리의 grep과 다를 바 없는 또 다른 에이전트 메모리 시스템이 나왔군요.”

@healthycoder – “이게 기존의 다른 메모리 기능들(mem0 등)과 무엇이 다른가요?”

@jrflo – “단순히 마크다운 파일을 사용하고 에이전트가 grep을 허용하는 것보다 왜 이게 더 유익한가요? MCP 도구가 에이전트의 속도를 늦추고 토큰을 낭비할 수 있다는 것을 알고 있습니다.”

@FitchApps – “초보자를 위해 왜 일반 MD 파일이 아닌 Google의 OKF 형식을 사용하는지 설명해 주실 수 있나요?”

@rcarmo – “더 많은 OKF 기반 접근 방식을 보게 되어 기쁩니다. 제 프로젝트는 https://rcarmo.github.io/projects/memento/ 입니다.”

이 댓글들은 두 가지 반복되는 주제를 보여줍니다: 일반 마크다운 대비 구조화된 OKF 메타데이터의 가치, 그리고 단순 grep 대비 SQLite 인덱스의 성능 트레이드오프입니다.

MCP-Memory가 기존 솔루션과 다른 점

  • 표준화된 메타데이터 – OKF v0.2는 일반 마크다운에는 없는 균일한 스키마(type, tags, status, provenance)를 강제하여, 더 풍부한 필터링과 자동화된 라이프사이클 관리를 가능하게 합니다.
  • 20ms 미만의 인덱싱된 조회 – SQLite FTS5는 결정론적 지연 시간을 제공하는 반면, grep은 파일 크기에 따라 선형적으로 확장되어 대규모 프로젝트에서 병목 현상이 될 수 있습니다.
  • 이중 지속성 – 에이전트는 데이터베이스를 통해 즉각적인 기계 판독 가능 액세스를 얻는 동시에, 개발자는 검토 및 버전 관리를 위해 사람이 읽을 수 있는 마크다운 아카이브를 유지할 수 있습니다.
  • 네임스페이스 격리 – 별도의 지식 도메인을 위한 내장 지원을 통해 관련 없는 프로젝트 간의 의도치 않은 간섭을 방지합니다.

MCP-Memory를 사용해야 할 때

  • 수십 개에서 수천 개의 지식 스니펫에 대한 빠르고 결정론적인 검색이 필요한 프로젝트.
  • **감사 가능성(auditability)**을 원하는 팀: 마크다운 디렉토리는 버전 관리가 가능하며, 데이터베이스는 에이전트를 구동합니다.
  • 컴플라이언스 또는 문서화를 위해 구조화된 출처(provenance)(소스, 검증, 상태)의 이점이 있는 워크플로우.

한계 및 미해결 과제

  • 내장된 벡터 검색 기능 없음; 메모리는 정확한 키, 태그 또는 전체 텍스트 일치로만 검색됩니다.
  • 성능 이득은 SQLite의 FTS5 설정에 따라 달라집니다; 매우 큰 코퍼스는 여전히 샤딩이 필요할 수 있습니다.
  • 일부 사용자는 에이전트가 서버에 반복적으로 쿼리를 보낼 경우 MCP 도구가 토큰 사용량을 증가시킬 수 있다고 보고합니다; 신중한 프롬프트 설계가 필요합니다.

결론

MCP-Memory는 Google의 Open Knowledge Format과 SQLite FTS5를 결합하여 사람이 읽을 수 있는 지식 베이스와 고성능 에이전트 메모리 사이의 간극을 메웁니다. 이중 레이어 설계, 네임스페이스 격리 및 제로 보일러플레이트 설정은 AI 에이전트를 위한 구조화되고 빠르며 지속적인 컨텍스트를 찾는 개발자에게 매력적인 옵션이 됩니다.

Sources

관련

  • 프로젝트
    Lyellr88/marm-memory

    Model Context Protocol (MCP)를 사용한 AI 에이전트를 위한 지속 가능한 로컬 메모리 서버로, 세션 간 공유되는 장기 기억, 코드 그래프, 개념 그래프를 제공합니다.

  • 프로젝트
    AVIDS2/memorix

    A local-first shared memory layer for AI coding agents that persists project context, design decisions, and Git history across different sessions and tools.

  • Dispatch
    MCP를 통한 코드 실행: 더 효율적인 AI 에이전트 구축하기

    Anthropic은 AI 에이전트가 직접적인 도구 호출 대신 코드 실행을 통해 Model Context Protocol (MCP) 서버와 상호작용하는 방식을 도입하여, 토큰 소비를 줄이고 효율성을 향상시킵니다.

  • 프로젝트
    Dicklesworthstone/mcp_agent_mail

    AI 코딩 에이전트를 위한 메일과 같은 조정 계층으로, 정체성, 비동기 메시징, 병렬 작업 중 충돌을 방지하기 위한 파일 예약 임대를 제공합니다.

  • 프로젝트
    oleksiijko/pmb

    PMB는 LLM 기반 코딩 어시스턴트에 로컬, SQLite 기반 메모리를 제공하는 오픈소스 Python 라이브러리입니다. 코드, PDF, git 기록 및 사용자가 기록한 사실을 자동으로 인덱싱한 다음 Model-Context-Protocol을 통해 가장 관련성이 높은 부분을 에이전트에 다시 주입합니다. 이 시스템은 오프라인으로 작동하며, 하이브리드 BM25 + 벡터 검색(웜 레이턴시 약 35ms)을 제공하고, 시각적 대시보드를 제공하며, 모델이 생각하기 전에 메모리를 불러오고 관찰된 작업을 자동으로 기록하는 훅을 모두 포함합니다. `pip install pmb-ai`로 설치하고, `pmb setup`을 실행하여 에이전트를 연결하면, 에이전트는 API 키나 클라우드 호출 없이도 재시작 간에 결정, 교훈 및 프로젝트 컨텍스트를 기억합니다.