VPS 기반 AI 에이전트 공유 메모리 Memmy 구축 방법
Memmy를 사용하여 여러 AI 에이전트가 단일 SQLite 저장소를 공유하도록 설정합니다. Ubuntu 서버에서 소스를 빌드하고 18960 포트로 메모리 서비스를 실행하여 로컬 환경에서 모든 데이터를 안전하게 관리하는 방법을 안내합니다.
Memmy의 정의와 저장 데이터
Memmy는 사용자의 VPS(가상 사설 서버)에서 실행되는 AI 에이전트를 위한 로컬 메모리 허브입니다. 에이전트가 학습한 내용을 하나의 SQLite 데이터베이스에 보관하며, 서버 내의 모든 에이전트가 동일한 저장소를 읽고 씁니다. 이 프로젝트는 MemTensor에서 제공하는 memmy-agent이며, 2026년 7월 기준 버전 1.0.4로 MIT 라이선스를 따릅니다.
서버에서는 이 중 일부만 필요합니다. Memmy는 http://127.0.0.1:18960에서 대기하는 메모리 서비스, 해당 서비스와 통신하는 memmy-memory 명령줄 인터페이스(CLI), 그리고 데스크톱 워크벤치를 제공합니다. 워크벤치는 macOS와 Windows용으로만 패키징되어 있으므로, Linux VPS에서는 서비스와 CLI만 실행하면 됩니다. 이것만으로도 Claude Code, Codex, Cursor에 공유 메모리를 제공하기에 충분합니다.
Memmy는 저장하는 데이터를 네 가지 계층으로 분류합니다. L1 Trace는 요청, 응답, 도구 호출을 포함한 원시 기록입니다. L2 Policy는 기록 중 유용하다고 판단된 절차를 도출한 것입니다. L3 World Model은 프로젝트나 환경에 대한 안정적인 지식입니다. Skill은 정책에서 구체화된 호출 가능한 절차입니다. 서비스가 기록을 수집할 때 계층을 자동으로 할당하므로, 사용자가 직접 생성할 필요는 없습니다.
공유 메모리 허브가 도구별 메모리와 비교하여 달라지는 점
오늘날 모든 에이전트는 각자의 메모리를 탑재하고 있습니다. Claude Code는 지침 파일을 저장소 내에 보관합니다. Cursor는 규칙을 워크스페이스 데이터베이스에 유지합니다. Codex는 세션 로그를 ~/.codex 아래에 보관합니다. 각 저장소는 하나의 도구에 귀속되므로, 월요일에 한 도구에서 가르친 사실을 화요일에 다른 도구는 알지 못합니다. 사용자는 이에 대해 두 번의 비용을 치릅니다. 한 번은 동일한 프로젝트를 다시 설명하는 데 소모되는 토큰 비용이며, 다른 한 번은 이미 다른 곳에서 수정한 내용을 에이전트가 반영하지 못해 발생하는 잘못된 작업 결과입니다.
허브는 저장소를 도구 밖으로 분리합니다. Memmy는 기존 저장소도 읽어 들이므로 빈 데이터베이스에서 시작할 필요가 없습니다. 스캐너는 ~/.claude/projects/**/*.jsonl의 Claude Code, ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl의 Codex, ~/.local/share/opencode/opencode.db의 OpenCode, state.vscdb의 Cursor 파일, ~/.openclaw 아래의 OpenClaw SQLite 데이터베이스, ~/.hermes의 Hermes 등 6가지 소스를 인식합니다. 이름과 로컬 경로를 지정하여 수동으로 소스를 추가할 수도 있습니다.
가져오기 카운터가 일치하지 않는 것은 정상입니다. 스캐너는 메시지를 소스와 대화별로 그룹화한 다음, 완료된 턴마다 하나의 L1 메모리를 작성합니다. 사용자 콘텐츠가 비어 있지 않고 어시스턴트 메시지도 비어 있지 않은 상태로 끝날 때 턴이 완료된 것으로 간주하므로, 중단된 세션은 아무런 데이터도 생성하지 않습니다. 메시지는 대화 체크포인트와 고정된 턴 ID를 사용하여 중복 제거됩니다. 따라서 동일한 실행 내에서도 스캔된 수, 가져온 메시지 수, 새로 생성된 메모리 수는 모두 다를 수 있습니다.
이 부분은 Claude Code가 단일 세션 내에서 컨텍스트를 관리하는 방식과 연계됩니다. 컨텍스트 관리는 단일 창에 무엇을 담을지 결정합니다. 메모리 허브는 해당 창이 닫힌 후 무엇을 남길지 결정합니다.
VPS에 필요한 사항
- Node.js 22 이상 버전. Memmy 문서에서 요구하는 사양이며, Ubuntu 24.04는 Node 18을 기본으로 제공합니다.
git및 빌드 툴체인.better-sqlite3은 설치 과정에서 컴파일이 필요할 수 있는 네이티브 모듈입니다.- 약 2 GB의 RAM. 루트 설치 시 대규모 워크스페이스와 프론트엔드 빌드 체인을 불러옵니다.
node_modules및 데이터베이스를 위한 수 GB의 여유 디스크 공간.
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 --versionnode --version 명령을 실행하면 v22 이상의 버전이 출력되어야 합니다. 여기서 v18이 출력된다면 NodeSource 설정 단계가 제대로 적용되지 않은 것이며, 이후 프로젝트의 엔진 검사 단계에서 설치가 실패하게 됩니다.
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:buildnpm run memory:build는 @memmy/memory 워크스페이스를 Memory/dist로 컴파일합니다. 헤드리스 서버에서는 트리 내의 다른 항목을 빌드할 필요가 없습니다. 네이티브 모듈이 로드되었는지 확인하십시오.
node -e "require('better-sqlite3'); console.log('better-sqlite3 loads')"해당 줄에서 출력 대신 오류가 발생한다면, 네이티브 모듈이 현재 Node 버전과 일치하지 않는 것입니다. 프로젝트의 시작 스크립트가 실행 전 수행하는 작업과 동일한 npm rebuild better-sqlite3를 실행하십시오.
README에는 bash scripts/dev-start.sh을 한 번의 명령으로 시작하는 방법이 기재되어 있습니다. 헤드리스 VPS에서는 이 명령을 실행하지 마십시오. 이 명령은 메모리 서비스와 함께 포트 19000에서 Electron 데스크톱 셸과 Vite 개발 서버를 시작합니다. Electron은 디스플레이가 필요하므로, 그래픽 세션이 없는 서버에서는 스크립트가 멈추거나 종료됩니다.
메모리 서비스를 시작하고 응답 확인하기
npm run memory:serve:dev이 방법은 소스에서 메모리 서비스를 실행하는 문서화된 방식입니다. 이 서비스는 127.0.0.1:18960에 바인딩되고, 데이터베이스를 ~/.memmy/memory-service/memory.sqlite에 유지하며, ~/.memmy/config.yaml에서 설정을 읽어옵니다. README에는 명시적으로 설정할 때 사용할 동일한 값들이 다음과 같이 기재되어 있습니다:
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/healthHealth 엔드포인트는 토큰을 요구하지 않는 유일한 엔드포인트이므로 상태 확인에 적합합니다. 만약 curl이 코드 7과 Failed to connect to 127.0.0.1 port 18960 메시지를 반환하며 종료된다면, 아무것도 리스닝 중이지 않은 상태입니다. 서비스가 실행 중인 터미널을 확인하십시오. 시작 시 발생하는 충돌은 해당 터미널에 출력되며, 일반적인 원인은 네이티브 SQLite 모듈을 로드하지 못하는 경우입니다. 서비스가 정상적으로 올라오면 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, 그리고 데스크톱 프론트엔드 개발 서버용 19000 및 19010이 사용됩니다. 시스템의 다른 프로세스가 이 포트 중 하나를 이미 점유하고 있다면 해당 목록을 확인해야 합니다.
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 healthPATH에 짧은 이름을 등록하고 싶다면, 동일한 파일을 다음과 같이 링크하십시오:
sudo ln -s "$PWD/Memory/dist/src/cli/index.js" /usr/local/bin/memmy-memory
memmy-memory healthCLI는 기본적으로 http://127.0.0.1:18960을 사용하며 --url, --token, --config, --source 및 --user-id 옵션을 허용합니다. 하위 명령으로는 init, health, search, add, get 및 delete이 있으며, 사람이 아닌 에이전트가 사용하는 session 및 turn 호출도 포함됩니다. 에이전트가 가장 많이 실행하는 두 가지 명령은 memmy-memory search "deploy steps"와 memmy-memory add "staging migrates on deploy"입니다.
Claude Code를 Memmy에 연결하는 방법
Claude Code에는 메모리 플러그인 인터페이스가 없으므로 Memmy가 직접 연동되지는 않습니다. 통합 방식은 그보다 더 단순합니다. Claude Code는 memmy-memory를 일반적인 셸 명령어로 실행하며, 지침 파일이 실행 시점을 알려줍니다. Memmy의 문서화된 설치 프로그램은 해당 파일을 자동으로 생성합니다. memmy-memory init --agent는 대상 에이전트의 규칙 디렉터리에 메모리 지침 파일을 배치합니다.
에이전트에게 어떤 지침이 전달되었는지 정확히 파악할 수 있도록 지침을 직접 한 번 작성해 보십시오. 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도 해당 메모를 확인할 수 있다는 차이점이 있습니다.
반대 방향의 연동은 별도의 설정이 필요 없습니다. Memmy 스캐너는 이미 Claude Code가 세션 기록을 저장하는 ~/.claude/projects/**/*.jsonl을 읽고 있습니다. tmux 세션 내의 Claude Code를 실행하는 동일한 서버에서 Memmy를 실행하면, 별도의 구성 없이도 이전 작업 내용이 메모리로 활용됩니다.
Does Memmy work as an MCP server for Claude Code?
No, and knowing the direction saves an afternoon. MCP (model context protocol) has clients and servers. Memmy is a client. It connects out to MCP servers and offers their tools to its own agent runtime. It does not publish an MCP endpoint that claude mcp add can point at. The only MCP bridge in the repository belongs to the Composio integration inside the desktop local API, and that API binds a random port on 127.0.0.1 behind its own x-memmy-mcp-token header.
The client side is configured in ~/.memmy/config.yaml, the file MEMMY_CONFIG points at, under tools.mcpServers:
tools:
mcpServers:
example:
type: stdio
command: npx
args:
- "-y"
- "your-mcp-server"
toolTimeout: 30
enabledTools:
- "*"type accepts stdio, sse and streamableHttp. A stdio server runs as a child process of Memmy, which means its command must exist on the same box and run as the same user. If you already keep MCP servers running on a VPS, those are the ones to list here.
메모리 저장소 비공개 유지하기
Memmy가 소유한 모든 데이터는 ~/.memmy 아래에 위치합니다. 여기에는 config.yaml, 작업 공간, memory-service/memory.sqlite 및 런타임 파일이 포함됩니다. 스캔과 수집은 로컬에서 수행되며, 메모리는 해당 로컬 SQLite 파일에 기록되므로 기본 상태는 완전히 로컬로 유지됩니다.
네트워크로 연결되는 경로는 두 가지입니다. MEMMY_CLOUD_SERVICE은 기본적으로 https://memmy-api.memtensor.cn를 사용하며 체험용 토큰으로 계정 모드를 지원하므로, API 키 모드에서는 해당 경로를 호출하지 않습니다. 메모리 개선 프로그램은 개인정보 설정에서 별도의 토글로 제공되며, 사용자가 직접 켜기 전까지는 꺼져 있습니다.
세 번째 경로는 간과하기 쉽습니다. 호스팅된 임베딩 제공자를 설정하면 모든 메모리의 텍스트가 벡터로 변환되기 위해 해당 제공자로 전송됩니다. 이 경우 로컬 저장소는 보호 수단이 되지 않습니다. 직접 호스팅하는 임베딩 엔드포인트를 사용하는 것만이 이 경로를 차단하는 유일한 방법입니다.
포트 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 환경 변수를 설정하면, 상태 확인 엔드포인트를 제외한 모든 엔드포인트에서 Bearer 토큰을 요구하게 됩니다. 설정 값은 ${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에서 메모리 서비스 실행하기
npm run memory:serve:dev를 셸에서 실행하면 셸이 종료될 때 함께 종료됩니다. 유닛 파일을 사용하면 재부팅 후에도 서비스를 계속 유지할 수 있습니다.
[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토큰을 유닛 파일에 포함하지 마십시오. root 소유이며 모드 600인 /etc/memmy/memory.env에 저장하십시오:
MEMMY_CONFIG=/home/memmy/.memmy/config.yaml
MEMMY_MEMORY_TOKEN=replace-this-with-a-long-random-stringsudo 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는 이를 찾지 못합니다. 시작하자마자 종료되는 유닛은 npm 내부에서 실패한 것이며, journalctl -u memmy-memory -n 50이 그 이유를 출력합니다. 작동 원리는 VPS의 다른 모든 systemd 서비스와 동일합니다.
Memmy가 아직 지원하지 않는 기능
- Linux 데스크톱 빌드가 없습니다. 패키징 스크립트는 macOS와 Windows만 지원하므로, 워크벤치, 온보딩 마법사, 메모리 대시보드는 서버 자체에서 사용할 수 없습니다.
memory:serve:dev는 개발 경로인tsx을 통해 TypeScript 진입점을 실행합니다. 저장소는 컴파일된 결과물을 위해memory:serve도 제공합니다. 현재 체크아웃에 어떤 스크립트가 있는지 확인하려면 인자 없이npm run를 실행하십시오.- 검색(Retrieval)은 최신 2,000개의 벡터 행에서 검색 윈도우를 구성한 뒤, 해당 윈도우 내에서 Top-K 선택을 적용합니다. 저장소가 매우 클 경우, 오래된 메모리는 검색 범위 밖에 위치할 수 있습니다.
- 임베딩은 캡처 이후에 발생하며, 실패 시 에이전트의 차례를 차단하는 대신 재시도 큐로 이동합니다. 따라서 방금 추가된 메모리는 벡터 검색으로 즉시 찾을 수 없을 수도 있습니다.
- 하나의 SQLite 파일은 하나의 노드를 의미합니다. 클러스터링 기능이 없으므로, 두 번째 서버는 별개의 독립적인 메모리로 작동합니다.
2026년 7월 기준 버전 1.0.4와 약 329개의 스타는 이 프로젝트가 아직 초기 단계임을 나타냅니다. 플래그, 경로, 스크립트 이름은 릴리스마다 변경될 수 있습니다. 이곳을 포함한 외부에서 복사한 명령어를 무조건 신뢰하기보다는, 본인의 체크아웃에서 bin 필드와 npm run의 출력 결과를 직접 확인하십시오.
FAQ
헬스 체크에서 connection refused가 발생하는 이유는 무엇입니까?
포트 18960에서 대기 중인 프로세스가 없기 때문입니다. Failed to connect to 127.0.0.1 port 18960과 함께 curl 종료 코드 7이 반환된다면 메모리 서비스가 실행 중이지 않거나 시작 시점에 종료된 것이므로, 서비스가 시작된 터미널이나 저널을 확인하십시오. 흔한 원인 두 가지는 Node 버전과 일치하지 않는 better-sqlite3 네이티브 모듈(npm rebuild better-sqlite3으로 해결 가능)과 22 미만의 Node 버전입니다. 서비스가 정상적으로 올라오면 ss -lntp | grep 18960 명령으로 소켓을 확인하십시오.
소스에서 빌드한 후 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에 접근하는 방식은 반대입니다. memmy-memory init --agent가 에이전트의 규칙 디렉터리에 작성하는 지침 파일에 따라 memmy-memory CLI를 셸 명령으로 실행하는 방식입니다.
Memmy를 실행하면 메모리가 클라우드 서비스로 전송됩니까?
스캔 및 수집은 로컬에서 수행되며, 메모리는 사용자의 디스크에 있는 ~/.memmy/memory-service/memory.sqlite에 기록됩니다. MEMMY_CLOUD_SERVICE은 계정 모드 및 체험 토큰을 위해 https://memmy-api.memtensor.cn을 가리키며, 메모리 개선 프로그램은 사용자가 직접 활성화하기 전까지는 꺼져 있습니다. 주의해야 할 경로는 임베딩 제공자입니다. 호스팅된 임베딩 모델은 벡터로 변환하는 모든 메모리의 텍스트를 수신하므로, 보안이 중요하다면 직접 실행하는 엔드포인트를 사용하십시오.