The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Memento listing page.
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.
| 경로 | 설명 |
|---|---|
packages/memento-core (@memento/core) | 도메인·인프라·공유 라이브러리. 진입점: createMementoCore, createToolContext, getToolRegistry, closeDatabase. DB 초기화·마이그레이션은 루트에서 npm run db:init / npm run db:migrate로 실행. |
| packages/memento-server | core를 사용하는 MCP/HTTP 서버. 루트 npm run dev, npm start, npm run dev:http 등으로 실행. |
packages/memento-client (@jee1/memento-client) | 서버 연결용 클라이언트 라이브러리. |
packages/memento-assistant (@jee1/memento-assistant) | 외부 AI 비서용 recall/remember SDK. |
packages/memento-agent-integration (@memento/agent-integration) | 에이전트 통합 계약·어댑터. 내부 전용(private), npm 미발행. |
| apps/ | 실험용 앱 (예: experimental-example은 @memento/core를 in-process로 사용). |
상세 구조·빌드·테스트 명령은 AGENTS.md를 참조하세요.
📦 패키지 매니저: 이 프로젝트는 npm을 사용합니다.
pnpm이나yarn은 지원하지 않습니다.
참고:
npm exec사용 시 명령어를 명시적으로 지정해야 합니다:
반복 사용 시 주의: 매번 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.
이 저장소 자체가 플러그인 마켓플레이스입니다. MCP 서버 등록과 recall→remember 사용 습관 skill이 함께 설치됩니다.
기억 DB는 ${CLAUDE_PLUGIN_DATA}/memory.db에 저장되어 플러그인을 업데이트해도 유지됩니다. 설치 후 /plugin 패널에서 memento MCP 서버가 연결됐는지 확인하세요.
Memento는 MCP 공식 레지스트리에 io.github.jee1/memento-mcp-server 이름으로 등재됩니다. 레지스트리를 읽는 클라이언트·마켓플레이스에서 이 이름으로 찾을 수 있습니다.
등재 메타데이터는 루트 server.json에 있고, 정식 릴리스마다 release.yml이 npm 배포 후 버전을 맞춰 자동으로 갱신합니다 (pre-release는 등재하지 않습니다).
이동된 환경 오버레이를 첫 파일로 사용할 때도 Compose 프로젝트 이름은 기본 memento로 유지됩니다. 다른 이름이 필요하면 COMPOSE_PROJECT_NAME을 설정하세요.
Log Issue Monitor: 운영 로그와 Docker diagnostics를 주기적으로 검사해 반복 오류를 GitHub Issue로 묶어 관리하려면 docker/docker-compose.issue-monitor.yml 오버레이를 사용합니다. 자세한 절차: Log Issue Monitor 운영 가이드.
SQLite는 WAL 모드를 사용해도 동시에 하나의 writer만 허용합니다. 여러 AI Agent가 각각 프로세스로 remember/forget을 호출하면 SQLITE_BUSY가 발생할 수 있으므로, 반드시 MCP 서버 프로세스를 하나만 띄워 DB를 전담하도록 구성하는 것을 권장합니다.
이 방식으로 packages/memento-server의 HTTP MCP 서비스를 띄워 두면, 모든 에이전트는 HTTP/WebSocket 인터페이스를 통해 이 서버에만 접속하고 SQLite writer는 단일 프로세스로 제한됩니다.
mcp.json)루트에서 npm run build 후 서버 실행 파일은 packages/memento-server/dist/server/http-server.js에 있습니다.
OpenClaw / NanoClaw / ZeroClaw 같은 개인 AI 비서가 Memento를 공유 장기 기억 백엔드로 사용할 수 있습니다. 가이드: docs/integrations/
@jee1/memento-assistant SDK를 사용하면 자동 recall/remember를 코드 두 줄로 붙일 수 있습니다 — SDK quickstart
세 가지 접근 방식으로 Memento에 연결할 수 있습니다.
@modelcontextprotocol/sdk): 커스텀 에이전트 코드에서 MCP 프로토콜로 직접 연결하는 방식@jee1/memento-client): TypeScript/JavaScript 코드에서 Memento 서버의 REST API를 프로그래밍 방식으로 사용하는 방식MCP 호스트 앱에서 Memento를 사용하려면 설정 파일에 서버 정보를 등록합니다.
npm run build 후 아래처럼 등록합니다.
파일 위치:
- 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(전역)
npx로 실행하는 경우 (소스 빌드 없이):
@modelcontextprotocol/sdk)@jee1/memento-client)@jee1/memento-client는 MCP 프로토콜이 아닌 HTTP REST API 래퍼입니다. TypeScript/JavaScript 애플리케이션에서 /tools/* 엔드포인트를 직접 호출할 때 사용합니다.
working, episodic, semantic, procedural 4가지 타입참고: 앵커 복원, 임베딩 마이그레이션, Episodic → Semantic 변환, 메타 메모리 통계는 MCP 도구가 아니라 HTTP 관리 API로만 제공됩니다.
텍스트와 의미(벡터)를 함께 검색한다. 키워드가 정확히 기억나지 않아도, 개념이 비슷하면 찾아낸다.
기억 시스템이 진짜 유용하려면, 망각도 설계해야 한다. 쌓이기만 하는 기억은 잡음이 된다.
보안: HTTP 서버는 브라우저 세션과 헤더 기반 신뢰 경계를 분리합니다.
/auth/session은 쿠키 기반 브라우저 세션을 시작하고,/admin과/api는 브라우저 세션이 필요하며,/api/v1/quality,/api/v1/maintenance,/tools,/mcp는Authorization: Bearer또는X-API-Key가 필요합니다. 자세한 내용: docs/reference/ko/security.md
HTTP 서버 실행 후 브라우저에서 기억들의 의미적 관계를 그래프로 시각화할 수 있습니다. 전체 관리 흐름은 /dashboard에서 여는 편이 가장 안전하며, /graph를 직접 열어도 동일한 /auth/session 기반 재인증 패널로 세션을 시작하거나 복구할 수 있습니다.

전체 문서 목록·KO/EN 매핑: docs/README.md
중요: 서버에는 도구 22개가 등록되어 있지만,
tools/list에는 기본적으로recall·remember·memory_injection·feedback4개만 노출됩니다(v1.18+). 도구 정의는 세션 내내 클라이언트 컨텍스트를 점유하므로, 늘 켜두는 서버일수록 기본 표면을 줄이는 편이 낫습니다(측정: 5,860 → 2,954 추정 토큰, 49.6% 감소).나머지 18개는 등록된 채로 남아 호출은 그대로 됩니다 — 목록에서만 빠집니다. 전부 나열하려면
MEMENTO_TOOLSET=full을 설정하세요. 관리/운영성 기능(앵커 복원, 임베딩 마이그레이션, Episodic→Semantic 변환, 메타 메모리 통계)은 여전히 HTTP API로만 제공됩니다.
| Tool | 설명 | 파라미터 |
|---|---|---|
remember | 기억 저장 | content, type, tags, importance, source, privacy_scope |
recall | 기억 검색 | query, filters, limit |
feedback | recall 결과 helpful/not_helpful 피드백 | memory_id, helpful |
pin | 기억 고정 | memory_id |
unpin | 기억 고정 해제 | memory_id |
forget | 기억 삭제 | memory_id, hard |
get_memory_neighbors | 이웃 기억 탐색 | memory_id, limit |
memory_injection | 컨텍스트 주입 프롬프트 생성 | query, token_budget |
| Tool | 설명 | 파라미터 |
|---|---|---|
set_anchor | 앵커 설정 | memory_id, slot |
get_anchor | 앵커 조회 | slot |
search_local | 앵커 주변 검색 | slot, query, limit |
clear_anchor | 앵커 제거 | slot |
| Tool | 설명 | 파라미터 |
|---|---|---|
remember_procedure | 절차 기억 저장 | content, workflow_name, skill_name, steps 등 |
procedural_diff | 절차 기억 버전 간 차이 비교 | left_id, right_id |
procedural_rollback | 절차 기억 이전 버전으로 복원 | current_id, target_version_id |
| Tool | 설명 | 파라미터 |
|---|---|---|
extract_triples | 본문에서 SPO 트리플 추출 | content 또는 messages |
add_relation | 기억 간 관계 추가 | source_id, target_id, relation_type |
get_relations | 관계 조회 | memory_id 등 |
remove_relation | 관계 삭제 | relation_id |
| Tool | 설명 | 파라미터 |
|---|---|---|
get_introspection_summary | 저신뢰·고실패 기억 요약 | — |
get_telemetry_summary | 검색·메모리 품질 텔레메트리 | period |
export_memories | 기억 내보내기 | filters 등 |
HTTP 전용 (MCP에 없음): restore_anchors, migrate_embeddings, convert_episodic_to_semantic, get_meta_memory_stats — 아래 HTTP 관리 API 참조.
중요: 다음 기능들은 MCP 클라이언트에 노출되지 않으며, HTTP API로만 제공됩니다.
| 엔드포인트 | 설명 | 메서드 |
|---|---|---|
/admin/memory/cleanup | 메모리 정리 | POST |
/admin/memory/convert-episodic-to-semantic | Episodic → Semantic 변환 | POST |
/admin/memory/meta-stats | 메타 메모리 통계 조회 | GET |
/admin/memory/review-candidates | 기억 리뷰 후보 목록 | GET |
/admin/memory/items/:memory_id | 단일 기억 프리뷰(JSON, 대시보드 등) | GET |
/admin/memory/review-candidates/:id/review | 기억 리뷰 후보 처리 | POST |
/admin/memory/review-candidates/:id/dismiss | 기억 리뷰 후보 기각 | POST |
/admin/stats/forgetting | 망각 통계 조회 | GET |
| 엔드포인트 | 설명 | 메서드 |
|---|---|---|
/api/v1/agent/personal:run | 한 턴 실행, 지식 후보 반환(저장 없음) | POST |
/api/v1/agent/personal:persist-approved | 승인된 후보만 remember로 저장 | POST |
사용 절차: 개인 지식 에이전트 HTTP 서버 런타임 사용법
| 엔드포인트 | 설명 | 메서드 |
|---|---|---|
/admin/anchors/restore | 앵커 복원 | POST |
| 엔드포인트 | 설명 | 메서드 |
|---|---|---|
/admin/embeddings/migrate | 임베딩 마이그레이션 | POST |
| 엔드포인트 | 설명 | 메서드 |
|---|---|---|
/admin/stats/performance | 성능 통계 조회 | GET |
/admin/alerts/performance | 성능 알림 조회 | GET |
| 엔드포인트 | 설명 | 메서드 |
|---|---|---|
/admin/stats/errors | 에러 통계 조회 | GET |
/admin/errors/resolve | 에러 해결 | POST |
| 엔드포인트 | 설명 | 메서드 |
|---|---|---|
/admin/database/optimize | 데이터베이스 최적화 | POST |
기타 HTTP admin: 배치 상태/실행(/admin/batch/*, jobType에 memory_review_candidates 포함), 성능 메트릭·알림(/admin/performance/*), 관계 추출·조회·시각화(/admin/relations/*) 등은 docs/api/ko/api-reference.md를 참고하세요.
| Resource | 설명 |
|---|---|
memory/{id} | 단일 기억 상세 정보 |
memory/search?query=... | 검색 결과 캐시 |
| 변수 | 기본값 | 설명 |
|---|---|---|
NODE_ENV | development | 실행 환경 |
PORT / MCP_SERVER_PORT | 9001 (http-server fallback) | HTTP/MCP 서버 포트 (env.example·Docker 권장: 9001) |
DB_PATH | ./data/memory.db | 데이터베이스 경로 |
LOG_LEVEL | info | 로그 레벨 |
OPENAI_API_KEY | - | OpenAI API 키 (선택사항) |
GEMINI_API_KEY | - | Gemini API 키 (선택사항) |
EMBEDDING_PROVIDER | minilm | 임베딩 제공자 (tfidf, lightweight, minilm, openai, gemini) |
CONSOLIDATION_SCORE_ENABLED | false | Consolidation Score System 활성화 여부 |
CONSOLIDATION_TEST_SEED_PATH | ./data/consolidation-seed.json | 테스트 Seed 데이터 파일 경로 |
CONSOLIDATION_BASELINE_PATH | ./data/consolidation-baseline.json | Baseline 스냅샷 저장 경로 |
CONSOLIDATION_TEST_ITEM_COUNT | 100 | 벤치마크 테스트 데이터 크기 |
CORS_ALLOWED_ORIGINS | (비어 있음) | CORS 허용 오리진 (쉼표 구분, 비어 있으면 크로스 오리진 미허용) |
ENABLE_PII_MASKING | true | PII 마스킹 활성화 (docs/reference/ko/security.md 참고) |
MEMORY_REVIEW_IMPORTANCE_THRESHOLD | 0.7 | 기억 리뷰 후보 최소 importance (0~1) |
MEMORY_REVIEW_STALE_DAYS | 14 | 기억 리뷰 후보 최소 stale 일수 (정수 ≥ 1) |
MEMORY_REVIEW_MAX_CANDIDATES | 50 | 기억 리뷰 후보 최대 개수 (정수 ≥ 1) |
MEMORY_REVIEW_MAX_BACKLOG | 500 | pending 후보가 이 수 이상이면 신규 선정을 건너뜀 (0: 비활성화) |
MEMORY_REVIEW_CANDIDATE_TTL_DAYS | 30 | 이 일수보다 오래된 pending 후보를 배치 실행 전에 만료 (0: 비활성화) |
MEMORY_REVIEW_CANDIDATES_INTERVAL_MS | 86400000 | 배치 스케줄 간격(ms), 최소 60000 |
MEMORY_REVIEW_CANDIDATE_DUE_DAYS | 14 | 배치가 due_at에 더하는 일 수 (1~366) |
참고: 망각 TTL, LLM/Ollama, 검색 한도 등 추가 변수는
env.example을 참고하세요.
공개 데이터셋(LongMemEval-S·LoCoMo)으로 검색 품질을 재는 하네스는 npm run quality -- longmemeval acquire·npm run quality -- locomo acquire로 데이터를 받은 뒤 npm run quality -- locomo benchmark로 돌립니다. 원본 데이터는 커밋하지 않으며, LoCoMo는 CC BY-NC 4.0(비상업) 이라 상업적 사용이 불가합니다. 절차와 현재 수치는 benchmark-datasets.md에 있고, 프로덕션 검색이 단순 FTS 베이스라인을 넘지 못한 상태라 대외 수치로 쓰지 않습니다.
packages/memento-core, packages/memento-server, packages/memento-client, apps/*. 상세: AGENTS.mdnpm run build(core→server→client), npm run dev·npm start(서버), npm run db:init·npm run db:migrate(DB), npm testpackages/*/src/**/*.spec.ts, 워크스페이스 수준 통합 스펙은 루트 tests/자동 선택 순서: 명시적 요청 → .env의 EMBEDDING_PROVIDER → OpenAI(1) → Gemini(2) → MiniLM(3) → TF-IDF(4). 상위 제공자 실패 시 자동 폴백.
Memento는 개인용 로컬 서버로 시작해, 팀 협업을 거쳐, 조직 규모의 메모리 플랫폼으로 성장하도록 설계되어 있다.
M1: 개인용 (현재) — 지금 사용할 수 있는 형태다. SQLite 임베디드, FTS5 + sqlite-vec 인덱스, 로컬 실행. 인증: 브라우저 세션 + 헤더 기반 분리 신뢰 모델(/auth/session 쿠키 세션, /admin·/api 브라우저 세션 요구, /tools·/mcp는 Bearer/API-Key 요구). MCP 도구 22개 등록·기본 노출 4개(MEMENTO_TOOLSET=full로 전체), 관리 기능은 HTTP API로 분리.
M2: 팀 협업 (계획) — SQLite 서버 모드, API Key 인증, Docker 단일 컨테이너. 여러 팀원이 하나의 기억 백엔드를 공유한다.
M3: 조직 (계획) — PostgreSQL + pgvector, JWT 인증, Docker Compose. 수백 명의 에이전트가 조직의 기억을 공유한다.
A: MCP(Model Context Protocol)를 지원하는 모든 AI Agent와 호환됩니다. Claude, GPT-4, Gemini 등과 연동 가능합니다.
A: 기본적으로 로컬 SQLite 데이터베이스(./data/memory.db)에 저장됩니다.
A: 선택사항입니다. API 키 없이도 TF-IDF 또는 MiniLM 기반 임베딩으로 동작합니다. 더 정확한 검색을 원한다면 OpenAI 또는 Gemini API 키를 설정하세요.
A: SQLite 데이터베이스 제한에 따라 달라집니다. 일반적으로 수백만 개의 기억을 저장할 수 있습니다.
A: 현재 M1은 개인용입니다. M2부터 팀 협업 기능이 추가될 예정입니다.
A: 망각 정책에 따라 자동으로 삭제됩니다. 중요한 기억은 pin 기능으로 고정할 수 있습니다.
Memento 프로젝트에 기여하고 싶으신가요? 자세한 가이드: CONTRIBUTING.md
git checkout -b feature/AmazingFeature)git commit -m 'feat: add some AmazingFeature')git push origin feature/AmazingFeature)이 프로젝트는 MIT License 하에 배포됩니다. package.json의 "license": "MIT" 와 동일합니다.