향상된 메모리 MCP 서버

지속 가능하고 검색 가능한 메모리로, AI 에이전트를 위해 Model Context Protocol 위에서 동작합니다. 엔티티와 그 관찰 내용은 체크섬과 버전 기록이 있는 압축 SQLite 데이터베이스에 저장되며, 계층형 저장소와 다중 전략 검색 파이프라인이 그 위에 있고, 전체는 MCP 도구로 클라이언트에 노출됩니다.

도구의 수는 설치한 항목에 따라 달라지며, 그 차이는 버그가 아닙니다. 백엔드가 누락된 도구는 전혀 등록되지 않습니다. 핵심 설치(requirements.txt)는 186개의 도구를 등록하며, 선택적 백엔드(requirements-optional.txt)를 추가하면 204개가 됩니다. 일반 pip install -r requirements.txt 후에 186개를 세었다면, 아무 문제가 없는 것입니다.

두 수치는 모두 Python 3.11.11에서 tools/list를 stdio로 실행하고 AGENTIC_SYSTEM_PATH가 설정되지 않은 상태에서 측정되었습니다. 마지막 조건은 현학적인 것이 아닙니다. 해당 변수가 GraphRAG에 설명된 별도 시스템을 가리키는 경우, 도구가 7개 더 등록되어 대신 193개와 211개가 됩니다. 이 파일의 이전 초안에서는 188개와 206개라고 표시되었는데, 이는 해당 변수가 내보내진 머신에서 측정되었고, 두 명의 작성자가 원인을 공유하는 것을 눈치채지 못한 채 같은 잘못된 숫자를 재현했기 때문입니다. 다시 측정하기 전에 설정을 해제하십시오.

모든 핵심 기능은 API 키나 네트워크 없이 로컬에서 실행됩니다. 선택적 벡터 스택(Qdrant + ollama)은 키워드 매칭에서 의미 기반 검색으로 검색 기능을 업그레이드하며, 해당 스택이 없어도 오류 없이 정상적으로 작동합니다.

가장 먼저 알아야 할 한 가지

이것은 하나가 아닌 두 개의 프로세스입니다. 이 프로젝트에 대한 거의 모든 지원 질문은 절반만 실행한 데서 비롯됩니다.

   your MCP client  (Claude Code, Claude Desktop, an SDK, curl)
            |
            |   stdio JSON-RPC, one server process per client session
            v
   +-------------------------------------------------------+
   |  MCP server            server.py                       |
   |  start with            setup/bin/mcp-server.sh          |
   +-------------------------------------------------------+
            |
            |   JSON over a Unix socket: $MEMORY_DB_SOCKET_PATH
            |   (default /tmp/memory-db.sock)
            v
   +-------------------------------------------------------+
   |  memory-db daemon      memory_db_service.py            |
   |  start with            setup/bin/memory-db-daemon.sh    |
   |  REQUIRED. Owns the database file exclusively so that   |
   |  several clients can share it without corrupting it.    |
   +-------------------------------------------------------+
            |
            v
     memory.db   (SQLite, default ~/.claude/enhanced_memories/)


   optional, off to the side:
     Qdrant  http://localhost:6333    vector index for semantic recall
     ollama  http://127.0.0.1:11434   local embeddings that feed that index

데몬은 선택 사항이 아니며 MCP 서버가 자동으로 시작하지 않습니다. 데몬 없이 서버는 여전히 시작되고 응답하며 다음과 같은 객체를 반환합니다:

{"query": "anything", "count": 0, "results": [],
 "error": "Memory-DB service error: [Errno 2] No such file or directory"}

{"error": "Memory-DB service error: ...", "entities": {"total": 0},
 "compression": {"ratio": "N/A"}}

잘 구성되어 있고 구문 분석 가능하지만 비어 있습니다. 이를 읽는 에이전트는 메모리가 비어 있다고 결론짓지, 듣지 못한다고 결론짓지 않습니다. ./healthcheck.sh는 이 둘을 구분하기 위해 존재합니다.

Related MCP server: Strata Memory MCP Server

사전 요구 사항

• Python 3.11 또는 그 이상. 일부 macOS 머신에서는 기본 python3가 여전히 3.9이므로, 설치 프로그램이 버전이 명시된 이름을 먼저 찾습니다.

• git 및 가상 환경을 위한 디스크 공간. macOS arm64에서 Python 3.11로 측정: 핵심 설치 시 83 MB, 선택적 백엔드 포함 시 964 MB (선택적 백엔드는 sentence-transformers와 torch를 가져오므로). Linux x86_64에서는 핵심 설치 시 131 MB (python:3.11-slim 컨테이너에서 측정) — 휠은 플랫폼에 따라 다르므로, 자신의 플랫폼에 따라 숫자가 달라질 수 있습니다. 체크아웃 자체는 5 MB입니다.

• 선택 사항: podman 또는 docker (컨테이너 경로 또는 로컬 Qdrant를 원하는 경우).

• 선택 사항: ollama (로컬 임베딩용).

• 어떤 지점에서도 sudo가 필요하지 않습니다. 시스템 전체에 설치되는 것은 없습니다.

이미 enhanced-memory 시스템을 실행 중인가요?

아래 2단계 전에 이 내용을 읽으십시오. 이 머신에 이미 이전 체크아웃, 두 번째 클론, 몇 달 전에 설치한 서비스가 있을 수 있습니다. 기본적으로 모든 설치는 동일한 두 가지, 즉 소켓 /tmp/memory-db.sock과 데이터베이스 ~/.claude/enhanced_memories/memory.db를 원하며, 이들은 공유할 수 없습니다.

먼저 확인하십시오:

lsof /tmp/memory-db.sock        # macOS or Linux
ss -xl | grep memory-db.sock    # Linux
pgrep -af memory_db_service.py

목록에 있는 것은 설치가 활성 상태임을 의미합니다. 점유된 소켓에서 두 번째 데몬을 시작하면 거부됩니다: 소켓을 가져오지 않고 0이 아닌 종료 코드로 종료되며, 소켓 경로와 응답 데몬이 사용 중인 데이터베이스를 출력합니다. 이는 보호 장치이지 공존이 아닙니다. 두 번째 데몬은 전혀 실행되지 않습니다.

두 개의 설치를 병렬로 실행하려면 이 설치에 .env에서 고유한 모든 것을 지정하십시오:

ENHANCED_MEMORY_DIR=/home/you/.enhanced-memory-second
MEMORY_DB_SOCKET_PATH=/tmp/memory-db-second.sock
# Only if you want the Neural Memory Fabric somewhere else again; by default it
# follows ENHANCED_MEMORY_DIR:
# NMF_SQLITE_PATH=/home/you/.enhanced-memory-second/nmf.db
# NMF_FILES_ROOT=/home/you/.enhanced-memory-second/nmf_files

ENHANCED_MEMORY_DIR은 잊혀지기 쉬운 변수입니다. 두 소켓에서 하나의 memory.db를 공유하는 두 데몬은 공존이 아닙니다: 하나의 파일에 대한 두 명의 독점 소유자이며, 이는 데몬이 정확히 방지하기 위해 존재하는 것입니다.

빠른 시작

git clone <this-repo> enhanced-memory-mcp
cd enhanced-memory-mcp

# 1. venv, dependencies, .env, database directory. Idempotent, re-runnable.
setup/setup.sh

# 2. start the daemon (foreground). Leave it running, or install it as a
#    background service: setup/service/install-services.sh
setup/bin/memory-db-daemon.sh &

# 3. prove the install works before you trust it
./healthcheck.sh

정상 실행은 Required checks passed.와 종료 코드 0으로 끝납니다. 다른 경우는 실제 문제입니다: 문제 해결을 참조하십시오.

설정은 .env에 있으며, 1단계는 .env가 없을 때만 .env.example에서 생성합니다. 해당 파일을 편집하는 것이 설정을 유지하는 방법입니다; setup/setup.sh를 다시 실행해도 덮어쓰지 않습니다.

그런 다음 MCP 클라이언트에 서버를 등록하십시오. ~/.claude.json에:

{
  "mcpServers": {
    "enhanced-memory": {
      "command": "/absolute/path/to/enhanced-memory-mcp/setup/bin/mcp-server.sh"
    }
  }
}

클라이언트가 python server.py가 아닌 런처를 가리키게 하십시오. 런처는 이 체크아웃의 .env를 적용하여 MCP 서버와 데몬이 동일한 데이터베이스 파일을 확인하도록 보장합니다. Python을 직접 실행하는 클라이언트는 해당 클라이언트가 가지고 있던 환경만 상속받으며, 두 프로세스는 조용히 분리됩니다. 분할 두뇌 함정을 참조하십시오.

이 시점에서 설치가 완료되고 도구가 호출될 때 작동합니다. 자체적으로 호출되는 것은 없습니다: 모든 세션은 빈 상태로 시작되며, 에이전트가 선택하지 않는 한 아무것도 기록되지 않습니다. 이는 결함이 아니며 어떤 검사도 보고하지 않으므로, 작동하는 설치를 작동하는 메모리로 착각하기 쉽습니다. docs/AUTOMATION.md에서 이 차이를 해결하는 방법을 다루며, 모든 프롬프트에서 실행되는 회상 훅으로 시작합니다.

대안: 하나의 공유 HTTP 서버

stdio는 클라이언트 세션당 하나의 서버 프로세스를 생성하며, 이는 데스크톱 클라이언트가 기대하는 방식입니다. HTTP를 통해 단일 공유 서버를 실행하려면 SSE 전송을 사용하십시오:

MCP_TRANSPORT=sse setup/bin/mcp-server.sh     # or setup/bin/mcp-server-sse.sh

{
  "mcpServers": {
    "enhanced-memory": { "type": "sse", "url": "http://127.0.0.1:9106/sse" }
  }
}

해당 포트에는 인증이 없습니다. MCP_HOST를 127.0.0.1로 유지하십시오.

구성

구성은 환경 변수입니다. setup/setup.sh는 .env.example에서 .env를 작성하며, 모든 설정을 인라인으로 문서화합니다. .env를 편집하는 것이 지속적인 메커니즘입니다: 복사는 .env가 존재하지 않을 때만 발생하므로, 편집 내용은 설치 프로그램을 다시 실행할 때마다 유지됩니다(같은 이유로 새 릴리스의 기본값이 자동으로 적용되지 않습니다. 업그레이드 후 두 파일을 비교하십시오). 이미 환경에 설정된 변수는 해당 호출에 대해 파일보다 우선합니다:

MEMORY_DB_SOCKET_PATH=/tmp/other.sock ./healthcheck.sh

ENHANCED_MEMORY_SURFACE와 MEMORY_PROFILE은 모두 tools/list가 반환하는 도구 수를 변경하며, 설치된 선택적 종속성도 영향을 미칩니다. 백엔드가 누락된 도구는 등록되지 않습니다. 코어 전용 설치와 선택적 추가 기능이 있는 설치는 동일한 코드에서 다른 개수를 보고합니다. 예상 도구 수는 세 가지 모두와 함께 있을 때만 의미가 있습니다.

선택적 서비스, 그리고 없을 때 잃는 것

둘 다 필수는 아닙니다. 둘 다 가질 가치가 있습니다.

둘 중 하나 또는 둘 다를 준비하세요:

setup/setup.sh --with-qdrant     # container on 127.0.0.1:6333, named volume
setup/setup.sh --with-ollama     # verifies ollama, pulls the embedding model

./healthcheck.sh는 둘 다 OPTIONAL로 보고하며, 없어도 게이트를 실패시키지 않습니다. 더 엄격한 계약을 원한다면 --require-optional을 전달하세요.

이미 Qdrant를 실행 중인가요? MEMORY_QDRANT_URL을 가리키고 --with-qdrant를 완전히 건너뛰세요. 여기서 인스턴스를 소유할 필요가 없습니다. 아래 컨테이너 프로필에서 논의된 포트 충돌은 해당 프로필에만 해당되며, 자체 컨테이너를 6333에 게시하고 다른 것이 이미 보유한 포트를 바인딩할 수 없습니다. 호스트 설치는 아웃바운드 요청만 합니다.

GraphRAG는 선택 사항이며 외부입니다.

GraphRAG 도구(graph_enhanced_search, get_entity_neighbors)는 여기에 포함되지 않습니다. graphrag_tools.py는 $AGENTIC_SYSTEM_PATH/scripts/graph-rag.py에서 구현을 로드합니다. 이 파일은 별도 시스템에 속하며 이 패키지의 일부가 아닙니다. AGENTIC_SYSTEM_PATH는 체크아웃의 상위 디렉터리로 기본 설정되므로 독립 실행형 설치에서는 해당 경로가 존재하지 않습니다.

아무것도 깨지지 않습니다. 등록이 래핑되어 서버는 GraphRAG integration skipped: ...를 기록하고 해당 도구 없이 시작됩니다. 해당 시스템이 있다면 AGENTIC_SYSTEM_PATH를 루트로 설정하면 등록됩니다. 건너뛰기 메시지는 로그 파일로 가며 터미널로 가지 않으므로, 없는 도구는 원래 없었던 도구처럼 보입니다.

컨테이너에서 실행

공유 환경을 위한 전달 경로. Podman 우선, docker 호환.

podman-compose up --build                              # core only
WITH_OPTIONAL=1 podman-compose --profile qdrant up     # with a USABLE vector store

WITH_OPTIONAL=1은 qdrant 프로필에서 중요합니다. 기본 이미지는 requirements.txt만 설치하며, 여기에는 qdrant-client가 포함되지 않습니다. 따라서 --profile qdrant를 사용하면 건강하고 접근 가능하지만 완전히 사용되지 않는 Qdrant가 제공됩니다. 상태 확인은 서비스에 접근 가능하다고 보고(참)하는 반면, 서버는 "qdrant-client not installed - vector search disabled"를 기록하고 모든 검색은 어휘 기반으로 유지됩니다. 비활성 기능 옆에 녹색 신호는 이 프로젝트가 제거하려는 정확한 실패 모드이므로, 여기서 직접 언급하여 여러분이 찾도록 남겨두지 않습니다. WITH_OPTIONAL=1은 requirements-optional.txt로 이미지를 빌드하고 벡터 경로가 실제로 작동합니다. (측정 결과: qdrant 프로필과 함께 코어 이미지는 /readyz에 "all shards are ready"라고 응답했지만 아무것도 사용하지 않았습니다.)

하이픈을 사용하세요. Fedora 44에서 podman compose(공백)는 외부 제공자(/usr/libexec/docker/cli-plugins/docker-compose)로 넘겨지며, 이는 Docker 호환 API 소켓이 필요합니다. podman.socket이 비활성화된 기본 상태에서는 podman compose up이 실패합니다:

failed to connect to the docker API at unix:///run/user/1000/podman/podman.sock:
  connect: no such file or directory

systemctl --user start podman.socket이 문제를 해결하거나, podman-compose(여기서는 1.6.0)를 사용하면 됩니다. podman-compose는 podman을 직접 구동하므로 소켓이 필요하지 않습니다. Fedora 44, podman 5.8.4에서 테스트: podman compose up은 위와 같이 실패했지만, podman-compose up -d는 스택을 올렸고 컨테이너는 healthy로 보고했습니다.

이미지는 container-entrypoint.sh에서 두 프로세스를 모두 실행합니다. 이 스크립트는 데몬을 시작하고, 소켓이 응답할 때까지 기다린 후에야 SSE 전송에서 MCP 서버를 시작합니다. 두 프로세스 중 하나라도 종료되면 컨테이너도 종료됩니다. 죽은 데몬 옆에 살아있는 MCP 서버가 있으면 영원히 올바른 형식의 0을 반환하는 상태가 되기 때문입니다.

시간을 절약해 줄 참고 사항:

• podman build는 HEALTHCHECK를 폐기합니다. Podman은 기본적으로 OCI 이미지 형식을 사용하며, 이 형식에는 healthcheck 필드가 없습니다. 빌드 시 한 번 경고합니다:

  HEALTHCHECK is not supported for OCI image format and will be ignored.
  Must use `docker` format

  빌드 출력에서 해당 줄을 놓치면 다시는 언급되지 않습니다. 이미지에는 healthcheck가 없으며 podman ps는 health 상태를 전혀 표시하지 않습니다. podman 5.8.4, Fedora 44에서 측정: OCI 이미지의 .HealthCheck는 nil로 검사되며, podman build --format docker로 다시 빌드하면 [CMD /app/setup/lib/container-health.sh]가 제공됩니다.

  세 가지 해결 방법(모두 확인됨): --format docker로 빌드, compose.yaml에 서비스 수준 healthcheck가 정의되어 이미지 형식에 관계없이 적용되는 compose 사용(compose에서 관리하는 컨테이너는 nil로 검사되는 동일한 이미지에서도 healthy로 보고), 또는 podman exec <name> /app/healthcheck.sh --skip-mcp로 요청 시 확인.

• MCP 포트는 호스트 루프백만 게시됩니다(127.0.0.1:9106:9106). 컨테이너 내부에서 서버는 0.0.0.0에 바인딩하는데, 이는 컨테이너 내에서는 올바르지만 워크스테이션에서는 잘못된 것입니다.

• Qdrant의 호스트 포트는 ${QDRANT_PORT:-6333} 및 ${QDRANT_ADMIN_PORT:-6334}입니다. 이미 Qdrant를 6333에서 실행 중이라면 .env에서 설정하세요. 그렇지 않으면 바인드 충돌이 발생하여 프로필이 시작되지 않습니다.

• 이미지는 핵심 설치이므로 qdrant 프로필은 자체적으로 아무 작업도 수행하지 않습니다. podman-compose --profile qdrant up을 실행하면 Qdrant가 시작되고, healthcheck를 통과하며 포트에서 응답하지만, 서버에는 통신할 qdrant-client가 없습니다. 모든 것이 녹색으로 보이지만 아무것도 인덱싱되지 않습니다. 실제로 사용하려면 선택적 스택을 사용하여 빌드하세요:

  podman build --build-arg WITH_OPTIONAL=1 -t enhanced-memory:local -f Containerfile .
  # or, through compose:
  WITH_OPTIONAL=1 podman-compose up --build

  ./healthcheck.sh는 두 경우를 구분합니다. 클라이언트 라이브러리를 가져올 수 있을 때만 Qdrant가 도달 가능하고 사용 가능하다고 보고하며, 서비스가 실행 중이지만 아무도 사용할 수 없을 때 경고합니다.

• 데이터베이스는 명명된 볼륨 enhanced-memory-data에 있습니다. 볼륨이 없으면 메모리가 컨테이너와 함께 사라집니다.

• ollama는 호스트에서 실행되며 컨테이너는 127.0.0.1에서 접근할 수 없습니다. compose.yaml에서 MEMORY_OLLAMA_URL의 주석을 해제하세요(podman의 경우 host.containers.internal, docker의 경우 host.docker.internal).

• 실행 중인 컨테이너는 호스트 설치를 확인하는 것과 동일한 방식으로 확인하세요. 절대 경로를 사용하세요. 모든 엔진이 WORKDIR에 대한 상대 경로를 확인하는 것은 아닙니다.

  podman exec enhanced-memory /app/healthcheck.sh --skip-mcp

• 로컬 .env는 컨테이너의 구성이 아닙니다. 이미지는 의도적으로 빈 .env를 제공하며, 모든 실제 구성은 compose.yaml의 런타임 환경에서 제공됩니다. .containerignore와 .dockerignore는 파일을 제외하지만 모든 엔진이 이를 준수하는 것은 아니므로(Apple의 container build는 준수하지 않았음, 2026-08-14 확인), Containerfile은 폐기된 빌드 단계에서도 이를 비운 후, 채워진 .env가 남아 있으면 빌드를 실패시킵니다.

백그라운드 서비스로 실행하기

setup/service/install-services.sh              # daemon only
setup/service/install-services.sh --with-sse   # and a shared SSE server
setup/service/uninstall-services.sh

macOS의 launchd 사용자 에이전트(~/Library/LaunchAgents), Linux의 systemd 사용자 유닛(~/.config/systemd/user). 루트 없음, 시스템 유닛 없음. 모든 경로는 이 체크아웃의 위치를 기준으로 생성되므로, 두 체크아웃은 서로 다른 --label-prefix 값, 다른 MEMORY_DB_SOCKET_PATH 값, 그리고 다른 ENHANCED_MEMORY_DIR 값을 부여하면 공존할 수 있습니다. 세 가지 모두, 처음 두 개만이 아닙니다. 소켓만 분리하면 두 데몬이 동일한 memory.db를 열게 되며, 각 데몬은 해당 파일을 독점적으로 소유해야 합니다.

설치 프로그램은 소켓을 기다리며 서비스가 시작되지 않으면 로그 꼬리를 표시하며 실패합니다. 로그는 의도적으로 체크아웃 디렉토리가 아닌 ~/Library/Logs/enhanced-memory 또는 ${XDG_STATE_HOME:-~/.local/state}/enhanced-memory/log에 저장됩니다. launchd는 생성 시 외부 볼륨에서 로그 파일을 생성할 수 없으며, 코드가 실행되기도 전에 작업이 종료 코드 78로 실패합니다.

Linux에서 사용자 유닛은 로그아웃 시 중지됩니다. 지속(lingering)을 활성화하지 않은 경우:

loginctl enable-linger $USER

설치 확인

다음 순서대로 두 개의 게이트가 있습니다.

./healthcheck.sh                 # the post-install gate
python3 comprehensive_test.py    # the functional suite (needs the daemon running)

개발자 대상의 세 번째 제품군은 tests/에 있으며 먼저 pip install -r dev-requirements.txt가 필요합니다. pytest는 의도적으로 어떤 런타임 요구 사항 파일에도 포함되지 않으며, 위의 두 게이트는 표준 라이브러리만으로 실행됩니다.

comprehensive_test.py는 통과 횟수가 아닌 종료 코드로 판단하세요. 검사 횟수는 선택한 모드에 따라 다릅니다. ENHANCED_MEMORY_* 또는 MEMORY_DB_* 변수가 설정되지 않은 경우 자체 샌드박스를 구축하고 모든 것을 실행하며, 설정된 경우 배포 대상에 대해 실행하고 생성하지 않은 샌드박스를 설명하는 검사를 건너뜁니다. 한 머신, 한 커밋에서 측정: 106개의 격리 검사와 102개의 운영자 지시 검사, 둘 다 종료 코드 0. 실행 시 자체 모드를 출력하고 건너뛴 항목의 이름을 지정합니다.

선택적 백엔드를 설치해도 그 수는 0만큼 변경됩니다(양쪽 모두 측정). 이 파일의 이전 개정판에서는 백엔드가 원인이라고 말했습니다. 그렇지 않으며, 누군가 테스트하기 전에 동일한 잘못된 추측이 pytest 건너뛰기 수에 첨부되었습니다. 실제로 그 수를 변화시키는 것이 무엇인지는 RELEASE_NOTES.md의 테스트 스위트 섹션을 참조하세요.

./healthcheck.sh는 실패할 수 있도록 설계되었습니다. 데몬 소켓을 통해 프로브 엔티티를 쓰고, 검색한 다음 삭제합니다. 모든 응답에서 error 또는 daemon 키를 나머지 페이로드와 관계없이 실패로 처리하며, 데몬이 보고하는 데이터베이스 경로를 환경이 확인하는 경로와 비교합니다. 다음을 확인합니다:

1. venv, 인터프리터 버전, .env, 소켓 경로 길이, 소스 존재 여부

2. 데몬 왕복(상태, 데이터베이스 일치, 쓰기, 읽기, 정리) 및 스키마 확인: 이 데이터베이스를 소유하는 두 파일의 모든 리터럴 INSERT를 라이브 테이블 정의와 비교합니다. 스키마에 없는 열은 모든 쓰기를 실패시키며 데몬은 예외를 발생시키는 대신 행별로 실패를 보고하기 때문입니다.

3. MCP 핸드셰이크(stdio), 도구 수, stdout 오염 여부

4. Qdrant 및 ollama, 선택 사항(OPTIONAL)으로 표시, 절대 치명적이지 않음

유용한 플래그: 빠른 데몬 전용 확인을 위한 --skip-mcp, 도구 수를 고정하는 --expect-tools N, 벡터 스택을 요구하는 --require-optional.

로그 위치

/tmp/enhanced-memory-mcp.log, 항상, 호스트의 모든 설치에 대해.

MCP 서버는 시작 시 모든 로깅 핸들러를 지우고 모든 것을 해당 순환 파일(50MB, 백업 2개)로 보냅니다. stdio 전송에서는 stdout의 모든 것이 프로토콜을 손상시키기 때문입니다. 일상적인 INFO는 거기에만 있으며, 경로는 고정되어 있으므로 한 머신의 두 체크아웃은 타임스탬프와 pid를 유일한 구분자로 동일한 파일에 인터리브됩니다.

WARNING 이상은 MEMORY_LOG_STDERR=0을 설정하지 않는 한 stderr로도 추가로 이동합니다. 이는 의도적인 것입니다. 모든 ... integration skipped: <reason> 줄은 로드되지 않은 기능이며, 이를 /tmp 아래의 파일로만 라우팅하면 아무도 읽지 않았습니다. MCP 클라이언트가 stderr 출력을 오류로 처리하는 경우 변수를 0으로 설정하고 대신 파일을 읽으세요.

./healthcheck.sh도 이를 WARN mcp-startup 줄로 보고하여 별개의 경고를 나열하므로, 누락된 기능이 로그에만 나타나는 것이 아니라 게이트에 표시됩니다. 이 브랜치에서 측정: 핵심 설치는 11개의 경고(numpy, qdrant-client, sentence-transformers, redis, neo4j 등)를 생성하고, 전체 설치는 3개를 생성합니다. 그 중 어느 것도 게이트를 실패시키지 않습니다. 이는 설치에 없는 기능의 목록이며, 한 번 읽고 무시할 가치가 있습니다.

이 릴리스의 서명 확인

커밋은 SSH로 서명됩니다. Git은 신뢰할 키를 알려줄 때까지 서명을 확인하지 않으며, 해당 구성은 클론과 함께 전송되지 않습니다:

git config gpg.ssh.allowedSignersFile .allowed_signers
git log --show-signature -1

첫 번째 줄 없이 git log --format=%G?는 모든 커밋에 대해 N을 보고합니다. 이는 "확인할 수 없음"을 의미하며 "서명되지 않음"이 아닙니다. 서명은 어느 쪽이든 존재합니다. git cat-file commit HEAD는 gpgsig 블록을 보여줍니다.

문제 해결

모든 도구가 0 또는 error 필드를 반환합니다

데몬이 실행되고 있지 않습니다. 이것이 압도적으로 일반적인 경우입니다.

{"count": 0, "results": [], "error": "Memory-DB service error: ..."}

setup/bin/memory-db-daemon.sh          # foreground, watch it
./healthcheck.sh --skip-mcp            # confirm the round trip

서버와 데몬이 데이터베이스에 대해 일치하지 않습니다

증상: 쓰기는 성공한 것처럼 보이지만 검색에서 찾을 수 없거나, get_memory_status가 저장한 것과 일치하지 않는 개수를 보고합니다. 두 프로세스가 다른 파일을 확인했으며, 둘 중 어느 것도 오류를 발생시키지 않습니다.

./healthcheck.sh가 직접 감지합니다:

FAIL db-agreement  SPLIT BRAIN: daemon holds /path/A/memory.db,
                   this environment resolves /path/B/memory.db

원인: 어떤 것이 하나의 프로세스를 다른 프로세스와 다른 ENHANCED_MEMORY_DIR, ENHANCED_MEMORY_DB_PATH 또는 HOME으로 시작했습니다. 일반적으로 .env를 적용하는 실행 프로그램을 우회하여 python server.py를 직접 실행하도록 구성된 MCP 클라이언트입니다. 클라이언트 구성을 수정하여 setup/bin/mcp-server.sh를 사용한 다음 두 프로세스를 다시 시작하세요.

콘텐츠 쿼리는 0을 반환하지만 이름 쿼리는 작동합니다

e9ca30c 이후로는 조용히 발생할 수 없습니다. 검색이 관찰 콘텐츠를 볼 수 없을 때 응답은 다음과 같이 말합니다 —

{"count": 0, "results": [], "degraded": "name-only (observations_fts missing)"}

degraded는 데이터베이스가 전체 텍스트 인덱스보다 먼저 생성되었으며 업그레이드 이후 데몬이 초기화되지 않았음을 의미합니다. 데몬을 다시 시작하세요. init_database()는 이제 인덱스를 생성하고 모든 기존 행을 백필합니다. 다른 값인 name-only (FTS query error)는 쿼리별 값이며, 쿼리 텍스트가 삭제 후 FTS 구문을 손상시켰음을 의미합니다. 이름/유형 일치는 여전히 실행되었습니다.

시드 재가져오기로 중복 관찰 항목이 추가됩니다

e9ca30c에서 수정됨: create_entities는 해당 엔티티에 대해 정확히 동일한 콘텐츠가 이미 존재하는 관찰 항목을 건너뛰고 응답에서 건너뛴 항목을 observations_deduped로 보고하므로, 반복적인 시드 가져오기는 멱등적입니다. 진정으로 새로운 관찰 항목은 여전히 추가됩니다. 수정 전 재가져오기로 생성된 중복 항목은 자동으로 삭제되지 않습니다. 문제 #8에 일회성 정리 SQL이 있습니다.

다시 작성된(약간 편집된 동일한 시드 파일) 재가져오기도 결정적 simhash를 통해 감지됩니다(LLM 불필요). 기본적으로는 near_duplicates 응답 필드에 저장 및 보고되며, 각각이 닮은 기존 행의 이름을 지정합니다. 수정("62Gi" → "125Gi")은 이 계층에서 다시 작성과 구별할 수 없으며, 메모리 저장소는 수정을 조용히 삭제해서는 안 됩니다. 재가져오기임을 알고 있는 가져오기 파이프라인은 ENHANCED_MEMORY_NEAR_DUP_POLICY=skip으로 설정하여 대신 삭제할 수 있습니다. 해당 변수의 다른 값은 안전한 저장 및 보고로 돌아갑니다. 거리 임계값 및 측정된 교정 밴드는 simhash_dedup.py에 있습니다.

데몬 시작 시 유용한 메시지 없이 OSError 발생

소켓 경로가 너무 깁니다. AF_UNIX는 macOS에서 104바이트, Linux에서 108바이트로 경로 문자열을 제한하며, bind()는 제한이나 경로를 언급하지 않는 오류와 함께 실패합니다. 깊은 체크아웃은 소켓이 체크아웃 내부에 배치되는 순간 이 문제가 발생합니다.

MEMORY_DB_SOCKET_PATH를 짧게 유지하고 체크아웃 외부에 두세요(예: /tmp/em-myproject.sock). setup/setup.sh는 이를 측정하고 너무 길면 계속 진행을 거부합니다.

macOS: 서비스는 설치되지만 데몬이 시작되지 않음

로그에 실행 프로그램 경로에 대한 Operation not permitted가 표시되면, 체크아웃이 launchd가 실행하도록 허용되지 않은 위치에 있는 것입니다. 2026-08-14 확인: /Volumes 아래 외부 볼륨의 체크아웃은 설치 및 로드는 잘 되지만, 모든 spawn은 EPERM으로 실패합니다. launchd는 터미널이 가지고 있는 디스크 액세스 권한 없이 실행되기 때문입니다.

체크아웃을 홈 디렉토리 또는 다른 로컬 경로로 이동하고 재설치하거나, 위치를 변경할 수 없는 경우 launchd에 전체 디스크 액세스 권한을 부여하세요. 설치 프로그램은 이를 숨기지 않고 표시합니다. 소켓을 기다렸다가 30초 후에 실패하며 오류 로그의 꼬리를 출력합니다.

소켓 파일이 있는 동안 ConnectionRefusedError 발생

죽은 데몬이 파일을 남겼습니다. 데몬을 다시 시작하면 파일을 자체적으로 제거하며 removed stale socket <path>를 로깅합니다. 런처도 exec 전에 동일한 작업을 수행합니다. 습관적으로 소켓 파일을 수동으로 삭제하지 마십시오. 여전히 서비스 중인 파일은 오래된 파일과 똑같이 보이며, 삭제하면 해당 데몬의 모든 클라이언트 연결이 끊어집니다.

REFUSING TO START: another daemon is already serving ...

의도된 동작입니다: 다른 무언가가 해당 소켓 경로에서 응답하고 있습니다. 메시지는 소켓 이름을 알려주며, 다른 데몬이 상태 요청에 응답할 때는 해당 데몬이 보유한 데이터베이스도 알려줍니다. 해당 데몬을 중지하거나, 이 데몬에 자체적인 MEMORY_DB_SOCKET_PATH 및 ENHANCED_MEMORY_DIR을 할당하십시오. — 이미 enhanced-memory 시스템을 실행 중이신가요?를 참조하세요.

MCP 클라이언트가 JSON 파싱 오류로 핸드셰이크에 실패합니다

무언가가 stdout에 출력되었습니다. stdout은 stdio 전송의 JSON-RPC 스트림 전용입니다. ./healthcheck.sh 검사 3은 이를 FAIL mcp-stdout으로 보고하며, 문제가 되는 줄도 함께 표시합니다.

python3이 3.9입니다

macOS에서 흔한 현상입니다. 지원되는 인터프리터를 설치하고(brew install python@3.11) setup/setup.sh를 다시 실행하십시오. 이 스크립트는 버전이 명시된 이름을 선호합니다. 특정 버전을 강제하려면: setup/setup.sh --python /path/to/python3.11

격차 및 알려진 문제

재확인을 위해 작성되었으며, 신뢰하지 마십시오.

• 헬스체크는 SSE 전송을 실행하지 않으며, 개별 도구를 호출하지 않고(목록만 표시), 여러 클라이언트의 동시 접근을 테스트하지 않으며, 벡터 스택 유무에 따른 검색 품질을 측정하지 않습니다.

• 이 README의 이전 개정판에 인용된 성능 수치는 여기서 재현되지 않았으며 반복 대신 제거되었습니다. 이 파일의 어떤 내용도 처리량, 지연 시간 또는 압축 비율을 주장하지 않습니다.

• 컨테이너 경로는 Fedora 44, linux/amd64에서 podman 5.8.4로 검증되었습니다: 빌드, 실행, 내부에서 전체 헬스체크 통과, 감독 테스트에서 Exited (1) 생성(엔트리포인트가 어떤 절반이 죽었는지 명명), podman-compose가 스택을 정상적으로 가동. 또한 개발 중 Apple의 container와 macOS/arm64의 Docker에서도 빌드 및 실행되었습니다. 포함되지 않은 사항: Fedora 44 이외의 배포판, rootful podman(위의 모든 것은 rootless였습니다).

• 서비스 유닛은 설치 프로그램에 의해 설치 및 시작되며, 설치 프로그램은 소켓을 기다리고 소켓이 나타나지 않으면 큰 소리로 실패합니다. 실제 재부팅 또는 로그아웃 후에도 유지되는지는 테스트되지 않았습니다.

• 도구 개수는 표면, 프로필 및 설치된 선택적 종속성에 따라 달라집니다. 단일 숫자는 특정 시스템 구성에 한정된 것으로 간주하십시오.

라이선스

MIT