🧠 Memento

🇰🇷 한국어 | 🇺🇸 English

LLM은 대화가 끝나면 모든 것을 잊는다. 이름도, 결정도, 지난 주에 함께 디버깅했던 맥락도. 이건 기술적 한계가 아니라 기억 인프라의 부재다.

Memento는 그 인프라다. 기억을 저장하는 데이터베이스가 아니라, 기억이 생성·분류·강화·망각되는 MCP 기반 기억 운영 체제.

기억은 단순하지 않다

심리학과 신경과학이 수십 년에 걸쳐 밝혀낸 것이 있다. 인간의 기억은 한 종류가 아니다.

작업기억(Working Memory) 은 지금 이 순간 처리 중인 정보다. 몇 초 안에 사라지지만, 그 순간만큼은 모든 판단의 기반이 된다. 일화기억(Episodic Memory) 은 경험의 흔적이다. "그날 오후 React Hook을 처음 배웠을 때"처럼 시간과 맥락이 붙어 있는 기억. 의미기억(Semantic Memory) 은 경험에서 증류된 지식이다. 수백 번의 디버깅을 거쳐 쌓인 "TypeScript 제네릭은 이렇게 동작한다"는 이해. 그리고 절차기억(Procedural Memory) 은 손에 밴 절차다. Docker 배포 순서, PR 체크리스트, 팀의 코딩 컨벤션.

현재 대부분의 LLM은 이 네 가지를 매 대화마다 잃는다. Memento는 이 네 가지를 모두 영속화한다 — remember 호출 시 type 파라미터로 working, episodic, semantic, procedural 중 하나를 지정하면 된다.

살아있는 기억

단순한 저장소가 아니다. Memento의 기억은 살아있다.

중요하게 쓰인 기억은 강화된다. 오래되고 쓸모없어진 기억은 망각 알고리즘에 의해 정리된다. 비슷한 기억들은 벡터 유사도로 서로 연결되어 그래프를 형성한다. 반복 사용하는 절차는 버전 관리되어 procedural_diff와 procedural_rollback으로 진화를 추적한다. 핵심 맥락은 앵커(Anchor)로 고정되어 새 대화에서도 즉시 복원된다.

AI가 "기억하는 척"하는 것이 아니라, 기억을 생성·분류·강화·망각하는 주체로 행동하게 만드는 것 — 그것이 Memento의 목표다.

📦 모노레포 구조

이 저장소는 npm workspaces 모노레포입니다. @memento/core가 도메인·DB·MCP 도구를 담고, memento-server가 stdio/HTTP로 이를 노출합니다. 앱이나 스크립트에서 REST로 붙을 때는 @jee1/memento-client, OpenClaw 같은 외부 비서에는 @jee1/memento-assistant, 에이전트 세션·프로버넌스 계약은 @memento/agent-integration이 담당하지만 이는 내부 전용 패키지로 npm에 발행되지 않습니다(서버 tarball에 번들). 실험 코드는 apps/ 아래에 두었습니다.

npm에 발행되는 패키지는 셋입니다: memento-mcp-server(서버), @jee1/memento-client, @jee1/memento-assistant.

npm i @jee1/memento-client      # REST 클라이언트
npm i @jee1/memento-assistant   # 외부 비서용 auto-recall/save SDK

상세 구조·빌드·테스트 명령은 AGENTS.md를 참조하세요.

🚀 빠른 시작

📦 패키지 매니저: 이 프로젝트는 npm을 사용합니다. pnpm이나 yarn은 지원하지 않습니다.

원클릭 설치 (권장)

curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash

npx 방식 (개발자용)

Windows (PowerShell/CMD)

npx memento-mcp-server@latest dev
npx memento-mcp-server@latest
npx memento-mcp-server@latest setup

Linux/macOS

npx memento-mcp-server@latest dev
npx memento-mcp-server@latest
npx memento-mcp-server@latest setup

참고: npm exec 사용 시 명령어를 명시적으로 지정해야 합니다:

Terminal

Copy

npm exec -- memento-mcp-server@latest dev

반복 사용 시 주의: 매번 npx로 실행하면 다운로드가 발생할 수 있으므로 반복 사용에는 글로벌 설치(npm i -g memento-mcp-server) 또는 로컬 설치 후 ./node_modules/.bin/memento 사용을 권장합니다. 모드 구분: MCP 서버(memento-mcp-server / stdio), HTTP 서버(memento-dev), CLI(memento — recall, remember, forget, memory_injection). CLI 가이드: docs/guides/ko/memento-cli-for-ai.md.

Claude Code 플러그인 (권장 — 설정 없이 한 번에)

이 저장소 자체가 플러그인 마켓플레이스입니다. MCP 서버 등록과 recall→remember 사용 습관 skill이 함께 설치됩니다.

/plugin marketplace add jee1/memento
/plugin install memento@memento

기억 DB는 ${CLAUDE_PLUGIN_DATA}/memory.db에 저장되어 플러그인을 업데이트해도 유지됩니다. 설치 후 /plugin 패널에서 memento MCP 서버가 연결됐는지 확인하세요.

MCP 공식 레지스트리

Memento는 MCP 공식 레지스트리에 io.github.jee1/memento-mcp-server 이름으로 등재됩니다. 레지스트리를 읽는 클라이언트·마켓플레이스에서 이 이름으로 찾을 수 있습니다.

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jee1/memento-mcp-server"

등재 메타데이터는 루트 server.json에 있고, 정식 릴리스마다 release.yml이 npm 배포 후 버전을 맞춰 자동으로 갱신합니다 (pre-release는 등재하지 않습니다).

Docker 방식 (프로덕션용)

docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.dev.yml up -d   # 개발
docker compose -p "${COMPOSE_PROJECT_NAME:-memento}" -f docker/docker-compose.prod.yml up -d  # 프로덕션

이동된 환경 오버레이를 첫 파일로 사용할 때도 Compose 프로젝트 이름은 기본 memento로 유지됩니다. 다른 이름이 필요하면 COMPOSE_PROJECT_NAME을 설정하세요.

Log Issue Monitor: 운영 로그와 Docker diagnostics를 주기적으로 검사해 반복 오류를 GitHub Issue로 묶어 관리하려면 docker/docker-compose.issue-monitor.yml 오버레이를 사용합니다. 자세한 절차: Log Issue Monitor 운영 가이드.

소스코드 방식 (개발자용)

git clone https://github.com/jee1/memento.git
cd memento
npm install
npm run build
npm run db:init
npm run db:migrate
npm run quick-start

다중 에이전트 운영을 위한 HTTP MCP 서버

SQLite는 WAL 모드를 사용해도 동시에 하나의 writer만 허용합니다. 여러 AI Agent가 각각 프로세스로 remember/forget을 호출하면 SQLITE_BUSY가 발생할 수 있으므로, 반드시 MCP 서버 프로세스를 하나만 띄워 DB를 전담하도록 구성하는 것을 권장합니다.

npm run dev:http                          # 개발 모드 (Hot Reload)
npm run build && npm run start:http       # 프로덕션

이 방식으로 packages/memento-server의 HTTP MCP 서비스를 띄워 두면, 모든 에이전트는 HTTP/WebSocket 인터페이스를 통해 이 서버에만 접속하고 SQLite writer는 단일 프로세스로 제한됩니다.

MCP 클라이언트 설정 예시 (mcp.json)

루트에서 npm run build 후 서버 실행 파일은 packages/memento-server/dist/server/http-server.js에 있습니다.

{
  "clients": {
    "memento": {
      "command": "node",
      "args": ["/path/to/memento/packages/memento-server/dist/server/http-server.js"],
      "env": {
        "DB_PATH": "/absolute/path/to/data/memory.db",
        "MCP_SERVER_PORT": "9001"
      },
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:9001/mcp"
      }
    }
  }
}

상세 설치 가이드

• INSTALL.md — 전체 설치 가이드
• Cursor MCP 설정 가이드
• npx 사용자 문제 해결

🔗 외부 AI 비서와 함께 쓰기

OpenClaw / NanoClaw / ZeroClaw 같은 개인 AI 비서가 Memento를 공유 장기 기억 백엔드로 사용할 수 있습니다. 가이드: docs/integrations/

@jee1/memento-assistant SDK를 사용하면 자동 recall/remember를 코드 두 줄로 붙일 수 있습니다 — SDK quickstart

💡 사용 예시

AI Agent와의 연동

// 일화기억으로 학습 내용 저장
await client.callTool({
  name: "remember",
  arguments: {
    content: "사용자는 React Hook을 학습했습니다. useState는 상태를 관리하고, useEffect는 사이드 이펙트를 처리합니다.",
    type: "episodic",
    tags: ["react", "hooks", "javascript"],
    importance: 0.8
  }
});

// 나중에 관련 기억 검색
const results = await client.callTool({
  name: "recall",
  arguments: {
    query: "React Hook은 어떻게 사용하나요?",
    limit: 5
  }
});

의미기억으로 지식 관리

// 경험에서 증류된 지식을 의미기억으로 저장
await client.callTool({
  name: "remember",
  arguments: {
    content: "TypeScript의 제네릭은 타입을 매개변수화하여 재사용 가능한 컴포넌트를 만드는 기능입니다.",
    type: "semantic",
    tags: ["typescript", "generics", "programming"],
    importance: 0.9
  }
});

절차기억으로 워크플로 보존

// 반복 작업 절차를 절차기억으로 저장 (버전 관리됨)
await client.callTool({
  name: "remember",
  arguments: {
    content: "Docker 컨테이너 빌드 및 배포 절차: 1) Dockerfile 작성 2) docker build 실행 3) docker run으로 테스트 4) 레지스트리에 푸시",
    type: "procedural",
    tags: ["docker", "deployment", "devops"],
    importance: 0.7
  }
});

🛠️ 사용법

세 가지 접근 방식으로 Memento에 연결할 수 있습니다.

• mcp.json 설정: Claude Desktop, Cursor, Claude Code 등 MCP 호스트에 Memento를 등록하는 방식 (코드 불필요)
• MCP 프로토콜 (@modelcontextprotocol/sdk): 커스텀 에이전트 코드에서 MCP 프로토콜로 직접 연결하는 방식
• HTTP API 클라이언트 (@jee1/memento-client): TypeScript/JavaScript 코드에서 Memento 서버의 REST API를 프로그래밍 방식으로 사용하는 방식

0. mcp.json 설정 (Claude Desktop · Cursor · Claude Code)

MCP 호스트 앱에서 Memento를 사용하려면 설정 파일에 서버 정보를 등록합니다.

stdio 모드 (단일 에이전트 / 소스 실행)

npm run build 후 아래처럼 등록합니다.

{
  "mcpServers": {
    "memento": {
      "command": "node",
      "args": ["/path/to/memento/packages/memento-server/dist/server/index.js"],
      "env": {
        "DB_PATH": "/absolute/path/to/data/memory.db"
      }
    }
  }
}

파일 위치:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Cursor: .cursor/mcp.json (프로젝트) 또는 ~/.cursor/mcp.json (전역)
• Claude Code: .claude/mcp.json (프로젝트) 또는 ~/.claude/mcp.json (전역)

HTTP MCP 모드 (다중 에이전트 공유 서버)

npm run build && npm run start:http   # 기본 포트: 9001 (env.example·Docker와 동일)

{
  "mcpServers": {
    "memento": {
      "type": "http",
      "url": "http://127.0.0.1:9001/mcp"
    }
  }
}

npx로 실행하는 경우 (소스 빌드 없이):

config.json

Copy

{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": ["memento-mcp-server@latest"],
      "env": {
        "DB_PATH": "/absolute/path/to/data/memory.db"
      }
    }
  }
}

1. MCP 프로토콜 연결 (@modelcontextprotocol/sdk)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client({
  name: "my-agent",
  version: "0.1.0"
}, {
  capabilities: { tools: {}, resources: {}, prompts: {} }
});

// stdio 연결 (단일 프로세스)
await client.connect({
  command: "node",
  args: ["packages/memento-server/dist/server/index.js"]
});

// HTTP MCP 연결 (다중 에이전트 공유 서버)
await client.connect({
  transport: {
    type: "http",
    url: "http://127.0.0.1:9001/mcp"
  }
});

const result = await client.callTool({
  name: "remember",
  arguments: {
    content: "React Hook에 대해 학습했습니다.",
    type: "episodic",
    tags: ["react", "hooks"],
    importance: 0.8
  }
});