memory-mcp

지속적인 에이전트 메모리를 위한 독립형 MCP 서버입니다 — 단기/장기 계층, 측정 가능한 신뢰성, 수명주기 유지보수 — SQLite(FTS5 + sqlite-vec)와 로컬 MiniLM 임베딩을 기반으로 합니다. 외부 서비스가 필요 없고 API 키도 필요 없습니다.

요구사항

• Node.js >= 22

• 이 패키지는 컴파일된 JavaScript로 제공되므로 런타임에 TypeScript 도구 체인이 필요하지 않습니다.

Related MCP server: localmem-mcp

설치

npm install @jommar/memory-mcp

두 가지 실행 파일이 제공됩니다:

빠른 시작

stdio(기본값)

MCP 클라이언트가 서버 바이너리를 가리키도록 지정하세요:

{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp-server"
    }
  }
}

또는 직접 실행하세요:

memory-mcp-server

npx를 사용할 때는 서버 bin을 직접 명시하세요(첫 사용 시 패키지가 설치됩니다):

npx -y -p @jommar/memory-mcp memory-mcp-server

HTTP(localhost 전용)

MEMORY_TRANSPORT=http memory-mcp-server

HTTP 엔드포인트는 기본적으로 127.0.0.1:3000에 바인딩되며, 동일한 엔드포인트에서 최신(2026-07-28) 및 구버전(2025-11-25) 프로토콜 버전을 모두 제공하므로 어떤 MCP 클라이언트든 연결할 수 있습니다. 서버는 무상태(stateless)이며 세션 ID가 필요하지 않습니다.

첫 실행

저장소는 ~/.memory-mcp/memory.db에 자동으로 생성됩니다. 임베딩은 **오프라인 우선(offline-first)**입니다. 즉, 직접 선택하지 않는 한 모델이 다운로드되지 않습니다.

# opt in to the one-time model download (about 23 MB, MiniLM-L6, q8 quantized)
MEMORY_EMBEDDING_OFFLINE=false memory-mcp-server

모델을 사용할 수 있을 때까지 remember와 recall는 계속 작동하며, 키워드 검색으로만 대체됩니다. 모델이 갖춰진 후에는 CLI의 reindex를 사용하여 벡터를 다시 채워 넣을 수 있습니다.

설정

모든 설정은 MEMORY_* 환경 변수로 이루어집니다(설정 파일 없음):

도구

remember, recall, get, update, forget, list, confirm, contradict, promote, consolidate 등 10가지 도구가 등록되어 있습니다. 입력값과 동작에 대한 전체 참조는 docs/tools.md를 참고하세요.

remember는 interactive 옵트인을 지원합니다: 거의 중복되는 항목을 찾으면 클라이언트에게 병합 또는 생성(MRTR)을 요청할 수 있으며, 대화형(interactive) 지원이 없는 클라이언트에서는 자동으로 기본 동작으로 정상 대체됩니다.

유지보수 CLI

memory-mcp export ./out      # write every memory as a markdown frontmatter file
memory-mcp import ./staging  # validate, then import (never overwrites existing keys)
memory-mcp reindex           # rebuild FTS + vector indexes from stored content
memory-mcp stats             # print store counts

문서

• docs/tools.md — 도구 참조

• docs/reliability.md — 신뢰성 모델과 라이프사이클 규칙 (consolidate의 기반이 되는 보고 전용 유지보수 엔진)

라이선스

MIT — LICENSE 파일을 참고하세요.