Memento MCP Server

🧠 Memento

🇰🇷 한국어 | 🇺🇸 English

---

LLM은 대화가 끝나면 모든 것을 잊습니다. 이름도, 결정도, 지난주에 쌓인 맥락도 마찬가지입니다. 이는 모델의 한계가 아니라 기억 인프라의 부재입니다.

Memento는 그 인프라입니다. 단순 저장소가 아니라, 기억이 생성·분류·강화·망각되는 MCP 기반 기억 운영 체제입니다.

작업기억·일화기억·의미기억·절차기억은 remember의 type으로 구분합니다. 쓰인 기억은 강화되고, 쓸모없어진 기억은 망각 정책으로 정리됩니다. 비슷한 기억은 벡터로 연결되며, 핵심 맥락은 앵커로 다음 대화에 바로 복원됩니다.

모노레포·패키지 구조·빌드 명령은 AGENTS.md를 참고해 주세요.

빠른 시작

패키지 매니저는 npm만 지원합니다 (pnpm/yarn은 지원하지 않습니다).

역할에 맞는 기본 경로 하나만 고르세요. Docker·소스 클론·다중 에이전트 HTTP·원클릭 스크립트는 INSTALL.md에 있습니다.

Claude Code → 플러그인

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

기억 DB는 ${CLAUDE_PLUGIN_DATA}/memory.db에 두어 플러그인 업데이트 후에도 유지됩니다. /plugin 패널에서 memento MCP가 연결됐는지 확인해 주세요. memento hook claude-code에서 lifecycle 캡처를 끄고 지침 주입만 쓰려면 MEMENTO_CAPTURE=0으로 설정합니다 (기본값: 1).

Cursor·기타 MCP → npx + mcp.json

npx memento-mcp-server@latest

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

설정 파일 위치는 다음과 같습니다. Cursor는 .cursor/mcp.json 또는 ~/.cursor/mcp.json입니다. Claude Desktop·Claude Code는 INSTALL.md와 Cursor MCP 설정 가이드를 참고해 주세요.

MCP 없이 터미널에서만 memento CLI를 쓰는 에이전트는 CLI agent skill(작업 전/후 recall·remember 워크플로)와 CLI for AI 가이드를 함께 참고해 주세요.

자주 쓴다면 npm i -g memento-mcp-server로 글로벌 설치하는 편이 낫습니다. 공식 MCP 레지스트리 이름은 io.github.jee1/memento-mcp-server입니다 (server.json).

글로벌 설치하면 memento CLI 도 함께 깔립니다. memento connect claude-code 가 등록하는 memento hook claude-code 훅이 이 명령을 씁니다.

운영·자체 호스팅 → INSTALL.md

Docker, 소스 빌드, HTTP MCP(다중 에이전트), 환경 오버레이는 INSTALL.md를 따라 주세요.

기본으로 보이는 도구

서버에는 도구 22개가 등록되어 있지만, tools/list에는 기본적으로 recall · remember · memory_injection · feedback 4개만 노출됩니다(v1.18+). 나머지는 등록된 채 호출은 가능하고, 목록에서만 빠집니다. 전부 나열하려면 MEMENTO_TOOLSET=full을 설정하세요.

사용 예시

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
  }
});

더 많은 연결 방식(MCP SDK, @jee1/memento-client, 외부 비서 SDK)은 docs/README.md와 docs/integrations/를 참고해 주세요.

핵심 기능

• 4종 기억: working · episodic · semantic · procedural
• 하이브리드 검색: FTS5 + 벡터, 태그 필터
• 살아있는 기억: 강화·망각·이웃 탐색·앵커
• 절차 버전: procedural_diff / procedural_rollback
• Case 지침 주입: Claude Code / Codex / Cursor 프롬프트마다 관련 지침만 고정 예산으로 주입. 서버 case 기억 또는 마크다운 폴더 (MEMENTO_DIRECTIVES_CASES_DIR) (가이드)
• 그래프·대시보드: HTTP 서버 기동 후 전체 관리 흐름은 /dashboard에서 여는 편이 가장 안전하며, /graph를 직접 열어도 동일한 /auth/session 기반 재인증 패널로 세션을 시작하거나 복구할 수 있습니다.

망각 TTL·임베딩·보안 등 설정값은 README에 숫자를 두지 않습니다. env.example가 기준입니다.

HTTP 보안 (관리 서버)

HTTP 서버는 브라우저 세션과 헤더 기반 신뢰 경계를 분리합니다. /auth/session은 쿠키 기반 브라우저 세션을 시작하고, /admin과 /api는 브라우저 세션이 필요하며, /api/v1/quality, /api/v1/maintenance, /tools, /mcp는 Authorization: Bearer 또는 X-API-Key가 필요합니다. 자세한 내용: docs/reference/ko/security.md.

HTTP 전용 (MCP에 없음): restore_anchors, migrate_embeddings, convert_episodic_to_semantic, get_meta_memory_stats — HTTP 관리 API 참조.

🧠 핵심 메모리 관리 (MCP 클라이언트)

참고: 도구 22개가 등록되어 있고, tools/list는 기본 4개만 노출합니다(MEMENTO_TOOLSET=full로 전체). 운영·관리 기능은 HTTP API로만 제공합니다.

문서

• 문서 포털: docs/README.md
• 설치: INSTALL.md · INSTALL.en.md
• 기여자·에이전트: AGENTS.md · CONTRIBUTING.md
• API: docs/api/ko/api-reference.md
• 보안: docs/reference/ko/security.md

로드맵 (요약)

• M1 개인용 (현재): 로컬 SQLite, MCP + HTTP 관리 API. 인증: 브라우저 세션 + 헤더 기반 분리 신뢰 모델(/auth/session 쿠키 세션, /admin·/api 브라우저 세션 요구, /tools·/mcp는 Bearer/API-Key 요구).
• M2 팀 (계획): 공유 백엔드, API Key, Docker
• M3 조직 (계획): PostgreSQL + pgvector, JWT

기여 · 라이선스 · 지원

기여는 CONTRIBUTING.md를 따라 주세요. 라이선스는 MIT입니다.

• 이슈: GitHub Issues
• 문서: docs/README.md