가이드

작성자 Matt Connor 2026-11-01 · 업데이트됨 2026-11-02

VPS 기반 AI 에이전트 통합 메모리 허브 Memmy 설정 방법

Q: 헬스 체크에서 왜 connection refused가 반환됩니까?

curl 종료 코드 7과 Failed to connect to 127.0.0.1 port 18960은 연결 실패를 의미하며, Memmy가 중지되었는지, 충돌했는지, 다른 곳에서 수신 중인지, 아니면 접근할 수 없는 상태인지를 나타내지는 않습니다. 주소와 포트를 확인하고 ss -lntp | grep 18960를 실행한 뒤, 서비스가 시작된 터미널이나 저널을 읽어 보십시오. 로그에 네이티브 SQLite 모듈 불일치가 보고된다면 npm rebuild better-sqlite3을 실행하십시오. Node 버전도 확인해야 합니다. 소스 문서에서는 Node 22 이상을 요구하지만, Linux 설치 프로그램은 22.x 버전 내에서는 Node.js 22.23.4 이상, 24.x 버전 내에서는 24.22.1 이상, 26.x 버전 내에서는 26.12.1 이상만 허용합니다.

Q: 소스에서 빌드한 후 memmy-memory 명령은 어디서 나옵니까?

저장소 이름이 아니라 @memmy/memory 워크스페이스 패키지의 bin 필드에서 나옵니다. 체크아웃 내부에서 node -p "JSON.stringify(require('./Memory/package.json').bin)"을 실행하면 {"memmy-memory":"./dist/src/cli/index.js"}이 출력됩니다. 해당 파일은 npm run memory:build 이후에만 존재합니다. 빌드 과정에서 dist을 생성하고 해당 파일을 실행 가능하도록 표시하기 때문입니다. node Memory/dist/src/cli/index.js health로 실행하거나, 짧은 이름을 사용하려면 /usr/local/bin로 심볼릭 링크를 생성하십시오.

Q: claude mcp add을 사용하여 Memmy를 Claude Code에 추가할 수 있습니까?

아니요. Memmy는 MCP 서버가 아니라 MCP 클라이언트입니다. Memmy는 ~/.memmy/config.yaml의 tools.mcpServers 아래에 나열된 서버에 외부로 연결하여 해당 도구를 자체 런타임에 제공합니다. Claude Code는 memmy-memory CLI를 셸 명령으로 실행하여 반대 방식으로 Memmy에 접근합니다. memmy-memory init --agent claude은 언제 실행할지 알려주는 Skill과 CLAUDE.md 블록을 작성하며, Linux 설치 프로그램의 런처는 턴을 자동으로 저장하는 Claude Code 후크도 추가합니다.

Q: Memmy를 실행하면 내 기억이 클라우드 서비스로 전송됩니까?

스캔 및 수집은 로컬에서 실행되며, 기억은 사용자의 디스크에 있는 ~/.memmy/memory-service/memory.sqlite에 기록됩니다. .env.example에서 https://api.memmy.cn로 설정된 MEMMY_CLOUD_SERVICE은 계정 모드와 체험용 토큰을 제공하며, 설정되어 있는 동안 기억 텍스트를 제외한 사용 분석 데이터를 수신합니다. 따라서 API 키만 사용하는 경우 해당 항목을 비워 두십시오. 기억 개선 프로그램에는 별도의 개인정보 보호 토글이 있습니다. 호스팅된 임베딩 모델은 벡터로 변환할 기억 텍스트를 수신합니다. 해당 처리를 로컬로 유지하려면 내장된 로컬 제공자나 직접 실행하는 엔드포인트를 사용하십시오. 호스팅된 요약, 진화 및 관련성 필터 모델도 해당 작업이 실행될 때 기억 콘텐츠를 수신합니다.

Memmy를 사용하여 여러 AI 에이전트가 로컬 SQLite 저장소를 공유하는 방법을 안내합니다. Ubuntu 서버에서 소스 빌드 후 18960 포트로 서비스를 실행하여 Claude Code와 Cursor의 메모리를 통합 관리하십시오.

Verified Every command ran end-to-end on a fresh Ubuntu 24.04 server, July 31, 2026.

Memmy의 정의와 저장 데이터

Memmy는 사용자의 VPS(가상 사설 서버)에서 실행되는 AI 에이전트용 로컬 메모리 허브입니다. 에이전트가 학습한 내용을 하나의 SQLite 데이터베이스에 보관하며, 서버 내의 모든 에이전트가 동일한 저장소를 읽고 씁니다. 이 프로젝트는 MemTensor에서 memmy-agent되었으며, MIT 라이선스를 따릅니다. 2026년 11월 1일 기준 버전은 1.2.401이며, Memory는 2.1.7 버전으로 독립 관리됩니다.

서버에서는 이 중 일부만 사용합니다. Memmy는 http://127.0.0.1:18960에서 대기하는 메모리 서비스, 해당 서비스와 통신하는 memmy-memory 명령줄 인터페이스(CLI), 그리고 데스크톱 워크벤치를 제공합니다. 워크벤치는 macOS와 Windows용으로만 패키징되어 있으므로, Linux VPS에서는 서비스와 CLI만 실행하면 됩니다. 이것만으로도 Claude Code, Codex, Cursor가 메모리를 공유하게 하기에 충분합니다.

Memmy는 저장 데이터를 4개의 계층으로 분류합니다. Capture는 먼저 개별 Raw Turn을 저장한 뒤, 요청, 응답, 도구 호출, 결과를 포함한 각 캡처 단계마다 하나의 L1 Trace 항목을 기록합니다. L2 Policy는 추적 결과 유용하다고 판단된 절차를 도출한 것입니다. L3 World Model은 프로젝트나 환경에 대한 안정적인 지식입니다. Skill은 정책에서 구체화된 호출 가능한 절차입니다. Capture는 L1 추적을 생성하고, 백그라운드 작업은 상위 계층을 발전시키며, 명시적 쓰기를 통해 계층을 선택할 수 있습니다. 이러한 구분이 추상적으로 느껴진다면, 메모리는 에이전트 구축 학습을 위한 단계별 경로의 후반부에 해당한다는 점을 참고하십시오. 직접 에이전트 루프를 작성하고 실행할 때마다 모든 것을 잊어버리는 과정을 지켜보고 나면 각 계층의 의미가 더 명확해질 것입니다.

공유 메모리 허브가 도구별 메모리와 비교하여 달라지는 점

오늘날 모든 에이전트는 각자의 메모리를 가지고 있습니다. Claude Code는 지침 파일을 저장소에 보관합니다. Cursor는 규칙을 작업 공간 데이터베이스에 유지합니다. Codex는 세션 로그를 ~/.codex 아래에 저장합니다. 각 저장소는 하나의 도구에 귀속되므로, 월요일에 한 도구에서 가르친 사실을 화요일에 다른 도구는 알지 못합니다. 사용자는 이에 대해 두 번의 비용을 치릅니다. 한 번은 같은 프로젝트를 다시 설명하는 데 소모되는 토큰 비용이며, 다른 한 번은 이미 다른 곳에서 수정한 가정을 바탕으로 에이전트가 잘못된 작업을 수행할 때 발생하는 비용입니다.

허브는 저장소를 도구 외부로 분리합니다. Memmy는 기존 저장소도 읽어 들이므로 빈 데이터베이스에서 시작할 필요가 없습니다. 스캐너는 10개의 내장 소스를 인식합니다. ~/.claude/projects/**/*.jsonl의 Claude Code, ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl의 Codex, ~/.local/share/opencode/opencode.db의 OpenCode, Cursor의 state.vscdb 파일, ~/.openclaw 아래의 OpenClaw SQLite 데이터베이스, ~/.hermes의 Hermes, ~/.dsh/sessions의 DeepSeek Harness, ~/.workbuddy/projects의 WorkBuddy, ~/.pi/agent/sessions의 Pi, ~/.qwenworkcn/projects의 QwenWork가 이에 해당합니다. 데스크톱 워크벤치에서는 이름을 지정하여 다른 에이전트를 추가할 수 있으며, 에이전트 자체를 찾을 수 없는 경우에만 기록 경로를 묻습니다. 서버 측 스캐너에는 사용자 지정 소스가 없으므로, 헤드리스 VPS에서는 내장 소스만 사용할 수 있습니다.

가져오기 카운터가 일치하지 않는 것은 정상입니다. 스캐너는 메시지를 소스 및 대화별로 그룹화한 다음, 완료된 턴마다 하나의 L1 메모리를 작성합니다. 턴은 비어 있지 않은 사용자 콘텐츠가 있고 비어 있지 않은 어시스턴트 메시지로 끝날 때 완료된 것으로 간주하므로, 완료되지 않은 턴은 나중에 동기화를 통해 완료될 때까지 아무런 기여를 하지 않습니다. 메시지는 대화 체크포인트와 안정적인 턴 ID를 사용하여 중복 제거됩니다. 따라서 동일한 실행 내에서도 스캔된 수, 가져온 메시지 수, 새로운 메모리 수는 모두 다를 수 있습니다.

이 부분은 Claude Code가 단일 세션 내에서 컨텍스트를 관리하는 방법과 연계됩니다. 컨텍스트 관리는 단일 창에 무엇을 담을지 결정합니다. 메모리 허브는 해당 창이 닫힌 후 무엇을 남길지 결정합니다.

VPS에 필요한 요구 사항

Node.js 22 이상. Memmy 문서에서 요구하는 사양이며, Ubuntu 24.04는 기본적으로 Node 18을 제공합니다.
git 및 빌드 도구 모음. better-sqlite3은 설치 과정에서 컴파일이 필요한 네이티브 모듈이기 때문입니다.
루트 워크스페이스 설치 및 프론트엔드 빌드 체인을 위한 RAM.
node_modules 및 데이터베이스를 위한 여유 디스크 공간.

sudo apt update
sudo apt install -y git build-essential python3 curl ca-certificates sqlite3
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version

node --version 명령은 문서화된 소스 빌드를 위해 v22 이상의 버전을 출력해야 합니다. 여기서 v18가 출력된다면 NodeSource 설정 단계가 제대로 적용되지 않은 것입니다. npm의 engine-strict 설정은 기본값이 false이므로, 호환되지 않는 엔진 선언이 있을 경우 일반적으로 설치가 자동으로 실패하기보다는 경고가 발생합니다.

Ubuntu 24.04에서 소스 코드로 Memmy 설치하기

git clone https://github.com/MemTensor/memmy-agent.git
cd memmy-agent
cp .env.example .env
npm install
npm run memory:build

npm run memory:build는 @memmy/memory 워크스페이스를 Memory/dist로 컴파일합니다. 또한 해당 워크스페이스에 필요한 AgentSourceCore, 메모리 뷰어, 통합 에셋을 빌드합니다. 네이티브 모듈이 정상적으로 로드되었는지 확인하십시오.

node -e "const Database = require('better-sqlite3'); const db = new Database(':memory:'); db.close(); console.log('better-sqlite3 loads')"

해당 줄에서 출력 대신 오류가 발생한다면, 오류 메시지를 읽어 로드 실패나 데이터베이스 초기화 실패 원인을 파악하십시오. 네이티브 모듈 불일치 문제가 발생하면 npm rebuild better-sqlite3을 실행하십시오. 이는 프로젝트의 시작 스크립트가 실행 전 수행하는 작업과 동일합니다.

README는 bash scripts/dev-start.sh를 한 번의 명령으로 시작하는 방법으로 안내합니다. 헤드리스 VPS에서는 이 명령을 실행하지 마십시오. 이 명령은 메모리 서비스와 함께 포트 19000에서 Electron 데스크톱 셸과 Vite 개발 서버를 시작합니다. Electron은 디스플레이 환경이 필요하므로, 그래픽 세션이 없는 서버에서는 스크립트가 멈추거나 종료됩니다.

최근 릴리스에는 Linux x64 및 arm64용 memmy-agent-linux-cli.tar.gz과 install.sh이 포함되어 있습니다. 설치 프로그램은 22.x 버전 내 Node.js 22.23.4 이상, 24.x 버전 내 24.22.1 이상, 또는 26.x 버전 내 26.12.1 이상을 요구하며, systemd 사용자 세션이 필요합니다. 다른 메이저 버전은 거부됩니다. 설치 프로그램은 memmy 및 memmy-memory 런처를 ~/.local/bin에 배치하고, 메모리 서비스를 127.0.0.1:18960에서 사용자 단위(user unit)로 시작합니다. 이 가이드에서는 모든 스크립트를 실행 전에 직접 검토할 수 있는 소스 빌드 방식을 유지합니다.

메모리 서비스를 시작하고 응답을 확인합니다

npm run memory:serve:dev

이것이 소스에서 메모리 서비스를 실행하는 문서화된 방법입니다. 이 명령은 127.0.0.1:18960에 바인딩하고, 데이터베이스를 ~/.memmy/memory-service/memory.sqlite에 유지하며, ~/.memmy/config.yaml에서 설정을 읽어옵니다. 서버는 명시적으로 지정하고 싶을 때 플래그로 동일한 값을 허용합니다:

npm run memory:serve:dev -- \
  --host 127.0.0.1 --port 18960 \
  --db ~/.memmy/memory-service/memory.sqlite \
  --config ~/.memmy/config.yaml

두 번째 셸에서 서비스가 활성화되어 있는지 확인합니다:

curl -sS http://127.0.0.1:18960/api/v1/health

Health는 토큰을 요구하지 않으므로 적절한 프로브입니다. 만약 curl이 코드 7과 Failed to connect to 127.0.0.1 port 18960 메시지를 반환하며 종료된다면 연결에 실패한 것입니다. 이것만으로는 리스너가 존재하는지 확인할 수 없습니다. 주소, 포트, 로컬 방화벽을 확인하고 서비스가 실행 중인 터미널에서 시작 오류를 읽어보십시오. 서비스가 정상적으로 올라오면 ss -lntp | grep 18960이 소켓을 확인해 줍니다.

나머지 HTTP API(애플리케이션 프로그래밍 인터페이스)는 /api/v1 아래에 위치합니다.

POST /api/v1/memory/add는 메모리를 작성하고 POST /api/v1/memory/search은 쿼리를 수행합니다.
GET /api/v1/memory/:id와 DELETE /api/v1/memory/:id는 항목 하나를 읽고 삭제합니다.
POST /api/v1/sessions/open과 POST /api/v1/sessions/:sessionId/close은 에이전트 세션을 시작하고 종료합니다.
POST /api/v1/turns/start과 POST /api/v1/turns/:turnId/complete는 한 턴을 기록합니다.
GET /api/v1/panel/overview, /api/v1/panel/analysis, /api/v1/panel/items는 대시보드에 데이터를 공급합니다.

Memmy는 포트 블록을 예약하며, 헤드리스 모드에서는 첫 번째 포트만 사용합니다. 메모리용 18960, 게이트웨이 상태용 18970, 웹 UI 및 관리자 HTTP용 18980, memmy serve이 시작하는 OpenAI 호환 API용 18990, 그리고 데스크톱 프론트엔드의 Vite 개발 서버용 19000과 핫 리로드 소켓용 19001을 사용합니다. 프로젝트의 포트 페이지에는 여전히 19010이 핫 리로드용으로 기재되어 있으나, Vite 설정은 19001로 되어 있습니다. 시스템의 다른 프로세스가 해당 포트 중 하나를 이미 점유하고 있다면 해당 목록을 확인하십시오.

memmy-memory 명령의 실제 출처

초기 설치 시 가장 자주 문제가 발생하는 부분이므로, 추측하지 말고 패키지 내용을 확인하십시오. 명령 이름은 저장소 이름과 아무런 관련이 없습니다. 이 명령은 해당 워크스페이스를 정의하는 bin 필드에서 유래합니다.

node -p "JSON.stringify(require('./Memory/package.json').bin)"

이 명령을 실행하면 {"memmy-memory":"./dist/src/cli/index.js"}이 출력됩니다. 따라서 빌드된 진입점은 Memory/dist/src/cli/index.js이며, 이는 npm run memory:build 이후에만 존재합니다. 빌드 과정에서 dist이 생성되고 해당 파일에 실행 권한이 부여되기 때문입니다. 직접 실행하려면 다음을 입력하십시오.

node Memory/dist/src/cli/index.js health

PATH에 짧은 이름을 등록하고 싶다면 동일한 파일을 링크하십시오.

sudo ln -s "$PWD/Memory/dist/src/cli/index.js" /usr/local/bin/memmy-memory
memmy-memory health

CLI는 기본적으로 http://127.0.0.1:18960를 사용하며 --url, --token, --config, --source 및 --user-id을 인자로 받습니다. 하위 명령으로는 init, health, search, add, get 및 delete이 있으며, 사람이 아닌 에이전트가 사용하는 session 및 turn 호출, 그리고 서비스 자체를 관리하기 위한 install, upgrade, service 및 stop이 있습니다. 에이전트가 가장 많이 실행하는 두 가지 명령은 memmy-memory search "deploy steps"과 memmy-memory add "staging migrates on deploy"입니다.

Claude Code를 Memmy에 연결하는 방법

Memmy는 Claude Code 내부에서 서버로 등록되지 않습니다. Claude Code가 이미 읽고 있는 파일을 통해 연결되며, 어떤 memmy-memory를 실행하느냐에 따라 연결 범위가 달라집니다. 소스 체크아웃 상태에서 memmy-memory init --agent claude를 실행하면 ~/.claude/skills/에 memmy-memory 스킬을, ~/.claude/CLAUDE.md에 표시된 메모리 블록을 기록합니다. 이후 Claude Code는 해당 지침에 따라 일반 셸 명령어로 memmy-memory를 실행합니다. Linux 설치 프로그램이 ~/.local/bin에 배치하는 런처는 더 많은 기능을 수행합니다. 동일한 명령어가 ~/.claude/settings.json 내의 SessionStart, UserPromptSubmit, Stop, PostCompact, SessionEnd에 대한 훅(hook)을 등록하여, 모델이 직접 결정하지 않아도 관련 메모리를 주입하고 완료된 각 턴을 저장합니다.

지침을 직접 한 번 작성해 보십시오. 그래야 에이전트에게 어떤 내용이 전달되었는지 정확히 파악할 수 있습니다. Claude Code는 세션 시작 시 프로젝트 루트에서 CLAUDE.md을 읽으므로, 아래와 같은 섹션이 소스 경로에서의 전체 통합을 의미합니다.

## Memory

Before starting a task, run `memmy-memory search "<topic>"` and read what comes back.
When a task is done, run `memmy-memory add "<what you learned>"` for anything that will matter next session.

이 통합이 어떤 이점을 제공하는지 명확히 이해해야 합니다. 훅이 없으면 명령어 수준의 통합이므로, 모델이 명령어를 실행하기로 결정했을 때만 작동합니다. 강제로 호출하는 기능은 없습니다. add 없이 세션이 종료되면 지침 자체는 아무것도 저장하지 않지만, 나중에 기록을 스캔하여 완료된 턴을 가져올 수는 있습니다. 이는 Claude Code 자체 메모리 파일과 동일한 트레이드오프를 가지지만, 저장소가 공유되므로 해당 메모가 동일한 머신에 있는 Codex와 Cursor에도 전달된다는 차이점이 있습니다. 훅은 모델의 판단에 의존하지 않고 간극을 메워주며, 이것이 바로 영구 메모리가 설치할 가치가 있는 DeepSeek Harness 플러그인 목록에서 예산 제한 및 권한 규칙과 함께 포함된 이유입니다.

반대 방향의 연결은 별도의 설정이 필요 없습니다. Memmy의 스캐너는 이미 Claude Code가 세션 기록을 저장하는 ~/.claude/projects/**/*.jsonl를 읽고 있습니다. tmux 세션 내의 Claude Code를 실행 중인 서버에서 Memmy를 실행하기만 하면, 별도의 구성 없이도 어제의 작업 내용이 메모리로 전환됩니다.

Memmy가 Claude Code를 위한 MCP 서버로 작동합니까?

아니요, 작동하지 않으며 이 방향성을 미리 아는 것이 시간을 절약하는 길입니다. MCP(Model Context Protocol)에는 클라이언트와 서버가 있습니다. Memmy는 클라이언트입니다. Memmy는 외부의 MCP 서버에 연결하여 해당 서버의 도구를 자체 에이전트 런타임에 제공합니다. Memmy는 claude mcp add이 가리킬 수 있는 MCP 엔드포인트를 게시하지 않습니다. 저장소 내의 유일한 MCP 브리지는 데스크톱 로컬 API 내부의 Composio 통합에 속하며, 해당 API는 자체 x-memmy-mcp-token 헤더 뒤의 127.0.0.1에서 임의의 포트를 바인딩합니다.

클라이언트 측은 ~/.memmy/config.yaml, 즉 MEMMY_CONFIG가 가리키는 파일의 tools.mcpServers 아래에서 설정됩니다:

tools:
  mcpServers:
    example:
      type: stdio
      command: npx
      args:
        - "-y"
        - "your-mcp-server"
      toolTimeout: 30
      enabledTools:
        - "*"

type은 stdio, sse 및 streamableHttp을 허용합니다. stdio 서버는 Memmy의 자식 프로세스로 실행되므로, 해당 명령은 동일한 장비에 존재해야 하며 동일한 사용자로 실행되어야 합니다. 만약 이미 VPS에서 실행 중인 MCP 서버를 유지 관리하고 있다면, 해당 서버들을 여기에 나열하면 됩니다.

메모리 저장소 비공개 유지하기

Memmy가 소유한 모든 데이터는 ~/.memmy 아래에 위치합니다. 여기에는 config.yaml, 작업 공간, memory-service/memory.sqlite 및 런타임 파일이 포함됩니다. 스캔과 수집은 로컬에서 이루어지며 메모리는 해당 로컬 SQLite 파일에 기록되므로, 기본적으로 데이터는 완전히 로컬에 머무릅니다.

클라우드 연결은 주의해야 할 경로 중 하나입니다. MEMMY_CLOUD_SERVICE은 클라우드 원본을 지정합니다. 코드에서 기본값을 설정하지는 않지만, 설치 과정에서 .env로 복사되는 .env.example 파일은 이를 https://api.memmy.cn으로 설정합니다. 이 설정은 체험용 토큰을 사용하는 계정 모드를 지원하며, 설정되어 있을 경우 Memmy의 분석 코드가 API 키 모드에서도 사용량 이벤트를 해당 주소로 전송합니다. 전송되는 정보에는 이벤트 및 명령어 이름, 버전, 설치 ID가 포함됩니다. CLI는 고정된 명령어 단어만 보고하며 검색 쿼리나 메모리 텍스트는 절대 전송하지 않습니다. 또한 값이 설정되지 않으면 분석 코드는 아무것도 전송하지 않으므로, API 키만 사용하는 서버라면 시작하기 전에 .env에서 해당 줄을 비워 두십시오. 메모리 개선 프로그램은 개인정보 보호 설정에서 별도로 켜고 끌 수 있습니다.

모델 호출 또한 또 다른 경로입니다. 호스팅된 임베딩 제공자를 설정하면 임베딩할 메모리 텍스트가 해당 제공자로 전송되어 벡터로 변환됩니다. 이 경우 로컬 저장소는 보호 수단이 되지 않습니다. 이 경로를 차단하려면 내장된 로컬 임베딩 제공자를 사용하거나 직접 호스팅하는 임베딩 엔드포인트를 사용하십시오. 호스팅된 요약, 진화 및 관련성 필터 모델 역시 작업 실행 시 메모리 콘텐츠를 수신하므로 해당 모델 설정도 확인해야 합니다.

포트 18960은 루프백 주소에 유지하십시오. 127.0.0.1에 바인딩된 서비스는 외부에서 전혀 접근할 수 없으므로 방화벽 규칙이 필요하지 않습니다. 대신 노트북에서 SSH를 통해 접근하십시오:

ssh -N -L 18960:127.0.0.1:18960 you@your-vps

현재 메모리 서비스는 루프백이 아닌 바인딩 주소를 거부합니다. 설정에서 storage.token를 지정하거나 MEMMY_MEMORY_TOKEN 또는 MEMORY_SERVICE_TOKEN 환경 변수를 설정하면 일반 메모리 API 호출을 베어러 토큰으로 보호할 수 있습니다. 상태 확인(health)은 인증 없이 유지되며, 브라우저 뷰어는 로컬 요청에 대해 별도의 검사를 수행합니다. 설정 값은 ${ENV_NAME} 참조를 지원하므로 토큰과 모델 API 키를 파일 자체에 노출하지 않을 수 있습니다. 이는 다른 모든 곳에서 AI 에이전트에서 비밀 정보를 제외하는 것과 동일한 습관이며, 향후 버전에서 기본 바인딩 주소가 변경될 경우를 대비해 기본 거부 ufw 정책을 최후의 보루로 삼으십시오.

신뢰하기 전에 ~/.memmy를 백업하십시오

memory.sqlite은 전체 저장소입니다. 벡터는 sqlite-vec 확장자를 통해 동일한 파일 내에 존재하므로, 파일 하나만 백업하면 됩니다. 서비스가 데이터를 기록하는 도중에 cp로 파일을 복사하면 데이터베이스가 손상될 수 있습니다. SQLite의 자체 백업 명령을 사용하십시오.

mkdir -p ~/memmy-backup
sqlite3 ~/.memmy/memory-service/memory.sqlite ".backup '$HOME/memmy-backup/memory.sqlite'"

이 명령은 서비스가 실행 중인 상태에서도 일관된 복사본을 생성합니다. 외부 저장소로 restic 백업을 사용하여 정기적으로 서버 외부로 데이터를 전송하십시오. config.yaml을 분실하면 다시 입력할 수 있는 공급자 설정이 사라집니다. memory.sqlite을 분실하면 마지막 백업 이후 기록된 기억이 모두 사라집니다. 서비스가 스키마 마이그레이션 전에 로컬 백업을 생성하기는 하지만, 이는 최신 외부 백업본이 아닙니다.

systemd에서 memory 서비스 실행하기

npm run memory:serve:dev을 셸에서 실행하면 셸이 종료될 때 함께 종료됩니다. unit 파일을 사용하면 재부팅 후에도 서비스를 계속 유지할 수 있습니다. 이 서비스는 memmy 사용자로 실행하며, /opt/memmy의 체크아웃 경로에서 해당 사용자의 홈 디렉터리에 있는 설정을 참조합니다. 셸에서 실행 중인 프로세스를 중지한 뒤, 체크아웃 디렉터리와 설정을 이동하고 memmy-memory 링크를 다시 연결하십시오:

sudo useradd -m -s /bin/bash memmy
sudo mkdir -p /opt/memmy
sudo mv ~/memmy-agent /opt/memmy/memmy-agent
sudo chown -R memmy:memmy /opt/memmy
sudo ln -sfn /opt/memmy/memmy-agent/Memory/dist/src/cli/index.js /usr/local/bin/memmy-memory
sudo install -d -o memmy -g memmy -m 700 /home/memmy/.memmy
sudo install -o memmy -g memmy -m 600 ~/.memmy/config.yaml /home/memmy/.memmy/config.yaml
sudo install -d -m 755 /etc/memmy

서비스는 /home/memmy/.memmy 경로에 데이터베이스를 저장하므로, 처음 시작할 때는 빈 저장소로 시작됩니다.

[Unit]
Description=Memmy memory service
After=network-online.target

[Service]
Type=simple
User=memmy
WorkingDirectory=/opt/memmy/memmy-agent
EnvironmentFile=/etc/memmy/memory.env
ExecStart=/usr/bin/npm run memory:serve:dev
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

토큰은 unit 파일에 포함하지 마십시오. root 소유, 권한 600으로 설정된 /etc/memmy/memory.env 파일에 저장하십시오:

MEMMY_CONFIG=/home/memmy/.memmy/config.yaml
MEMMY_MEMORY_TOKEN=replace-this-with-a-long-random-string

sudo systemctl daemon-reload
sudo systemctl enable --now memmy-memory
systemctl status memmy-memory --no-pager
curl -sS http://127.0.0.1:18960/api/v1/health

상태 출력에 status=203/EXEC가 표시되면 systemd가 ExecStart를 전혀 실행하지 못한 것이므로 which npm을 확인하십시오. NodeSource 설치 시에는 /usr/bin/npm 경로에 위치하며, nvm을 사용 중이라면 사용자 홈 디렉터리 하위에 위치하는데 systemd는 이를 찾지 못할 수 있습니다. 서비스가 시작되자마자 종료된다면 종료 상태와 저널을 확인해야 합니다. 코드 0은 정상 종료를 의미하며, 그 외의 결과는 0이 아닌 종료 코드, 시그널, 타임아웃 등을 포함합니다. 서비스의 출력을 보려면 journalctl -u memmy-memory -n 50을 실행하십시오. 작동 방식은 VPS의 다른 모든 systemd 서비스와 동일합니다.

현재 프로젝트는 두 가지 사용자 수준의 대안을 제공합니다. README에 명시된 소스 빌드 방식은 memmy-memory install --service-only를 사용하는 것으로, 고정된 Memory 런타임을 다운로드하고 사용자 서비스를 등록합니다. Linux 설치 프로그램은 memmy-memory.service을 systemd --user unit으로 설정합니다. 두 방식 모두 linger를 자동으로 활성화하지 않으므로, 로그아웃 후에도 사용자 서비스 관리자가 계속 실행되도록 하고 부팅 시 시작하게 하려면 sudo loginctl enable-linger <user>를 실행하십시오.

Memmy가 아직 지원하지 않는 기능

Linux 데스크톱 빌드가 없습니다. 패키징 스크립트는 macOS와 Windows만 지원하므로, 워크벤치와 온보딩 마법사는 서버 자체에서 사용할 수 없습니다. 메모리 서비스는 현재 http://127.0.0.1:18960/viewer/에서 브라우저 뷰어를 제공하며, 위에서 설명한 SSH 터널을 통해 접근할 수 있습니다. Linux 환경에서는 CLI tarball과 install.sh를 대신 사용합니다.
memory:serve:dev는 개발 경로인 tsx을 통해 TypeScript 진입점을 실행합니다. 저장소는 컴파일된 결과물을 위해 memory:serve도 제공합니다. 현재 체크아웃 환경에서 어떤 스크립트를 사용할 수 있는지 확인하려면 인자 없이 npm run을 실행하십시오.
검색(Retrieval) 기능은 최신 2,000개의 벡터 행에서 검색 윈도우를 구성한 뒤, 해당 윈도우 내에서 Top-K 선택을 적용합니다. 저장소가 매우 클 경우, 오래된 메모리는 검색 범위 밖에 위치할 수 있습니다.
임베딩은 캡처 이후에 수행되며, 실패 시 에이전트의 차례를 차단하는 대신 재시도 큐로 이동합니다. 방금 추가된 메모리는 벡터 검색으로 즉시 찾을 수 없을 수도 있습니다.
자체 로컬 SQLite 데이터베이스를 사용하는 두 번째 서버는 별도의 메모리를 가집니다.

2026년 11월 1일 기준 버전 1.2.401은 여전히 빠르게 변화하는 초기 단계의 프로젝트입니다. 플래그, 경로, 스크립트 이름은 릴리스마다 변경될 수 있습니다. 이곳을 포함한 외부에서 복사한 명령어를 무조건 신뢰하기보다는, 본인의 체크아웃 환경에서 bin 필드와 npm run의 출력 결과를 확인하십시오.

FAQ

헬스 체크에서 왜 connection refused가 반환됩니까?

curl 종료 코드 7과 Failed to connect to 127.0.0.1 port 18960은 연결 실패를 의미하며, Memmy가 중지되었는지, 충돌했는지, 다른 곳에서 수신 중인지, 아니면 접근할 수 없는 상태인지를 나타내지는 않습니다. 주소와 포트를 확인하고 ss -lntp | grep 18960를 실행한 뒤, 서비스가 시작된 터미널이나 저널을 읽어 보십시오. 로그에 네이티브 SQLite 모듈 불일치가 보고된다면 npm rebuild better-sqlite3을 실행하십시오. Node 버전도 확인해야 합니다. 소스 문서에서는 Node 22 이상을 요구하지만, Linux 설치 프로그램은 22.x 버전 내에서는 Node.js 22.23.4 이상, 24.x 버전 내에서는 24.22.1 이상, 26.x 버전 내에서는 26.12.1 이상만 허용합니다.

소스에서 빌드한 후 `memmy-memory` 명령은 어디서 나옵니까?

저장소 이름이 아니라 @memmy/memory 워크스페이스 패키지의 bin 필드에서 나옵니다. 체크아웃 내부에서 node -p "JSON.stringify(require('./Memory/package.json').bin)"을 실행하면 {"memmy-memory":"./dist/src/cli/index.js"}이 출력됩니다. 해당 파일은 npm run memory:build 이후에만 존재합니다. 빌드 과정에서 dist을 생성하고 해당 파일을 실행 가능하도록 표시하기 때문입니다. node Memory/dist/src/cli/index.js health로 실행하거나, 짧은 이름을 사용하려면 /usr/local/bin로 심볼릭 링크를 생성하십시오.

`claude mcp add`을 사용하여 Memmy를 Claude Code에 추가할 수 있습니까?

아니요. Memmy는 MCP 서버가 아니라 MCP 클라이언트입니다. Memmy는 ~/.memmy/config.yaml의 tools.mcpServers 아래에 나열된 서버에 외부로 연결하여 해당 도구를 자체 런타임에 제공합니다. Claude Code는 memmy-memory CLI를 셸 명령으로 실행하여 반대 방식으로 Memmy에 접근합니다. memmy-memory init --agent claude은 언제 실행할지 알려주는 Skill과 CLAUDE.md 블록을 작성하며, Linux 설치 프로그램의 런처는 턴을 자동으로 저장하는 Claude Code 후크도 추가합니다.

Memmy를 실행하면 내 기억이 클라우드 서비스로 전송됩니까?

스캔 및 수집은 로컬에서 실행되며, 기억은 사용자의 디스크에 있는 ~/.memmy/memory-service/memory.sqlite에 기록됩니다. .env.example에서 https://api.memmy.cn로 설정된 MEMMY_CLOUD_SERVICE은 계정 모드와 체험용 토큰을 제공하며, 설정되어 있는 동안 기억 텍스트를 제외한 사용 분석 데이터를 수신합니다. 따라서 API 키만 사용하는 경우 해당 항목을 비워 두십시오. 기억 개선 프로그램에는 별도의 개인정보 보호 토글이 있습니다. 호스팅된 임베딩 모델은 벡터로 변환할 기억 텍스트를 수신합니다. 해당 처리를 로컬로 유지하려면 내장된 로컬 제공자나 직접 실행하는 엔드포인트를 사용하십시오. 호스팅된 요약, 진화 및 관련성 필터 모델도 해당 작업이 실행될 때 기억 콘텐츠를 수신합니다.

이 글이 도움이 되었나요?

#memmy#memory #ai-agents #mcp #self-hosted