{
  "markdown": "# 🧠 Memento\n\n<div align=\"center\">\n  <img src=\"static/logo.png\" alt=\"Memento Logo\" width=\"200\" height=\"200\">\n\n  [🇰🇷 한국어](README.md) | [🇺🇸 English](README.en.md)\n\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n</div>\n\n---\n\nLLM은 대화가 끝나면 모든 것을 잊는다. 이름도, 결정도, 지난 주에 함께 디버깅했던 맥락도. 이건 기술적 한계가 아니라 **기억 인프라의 부재**다.\n\nMemento는 그 인프라다. 기억을 저장하는 데이터베이스가 아니라, 기억이 생성·분류·강화·망각되는 **MCP 기반 기억 운영 체제**.\n\n## 기억은 단순하지 않다\n\n심리학과 신경과학이 수십 년에 걸쳐 밝혀낸 것이 있다. 인간의 기억은 한 종류가 아니다.\n\n**작업기억(Working Memory)** 은 지금 이 순간 처리 중인 정보다. 몇 초 안에 사라지지만, 그 순간만큼은 모든 판단의 기반이 된다. **일화기억(Episodic Memory)** 은 경험의 흔적이다. \"그날 오후 React Hook을 처음 배웠을 때\"처럼 시간과 맥락이 붙어 있는 기억. **의미기억(Semantic Memory)** 은 경험에서 증류된 지식이다. 수백 번의 디버깅을 거쳐 쌓인 \"TypeScript 제네릭은 이렇게 동작한다\"는 이해. 그리고 **절차기억(Procedural Memory)** 은 손에 밴 절차다. Docker 배포 순서, PR 체크리스트, 팀의 코딩 컨벤션.\n\n현재 대부분의 LLM은 이 네 가지를 매 대화마다 잃는다. Memento는 이 네 가지를 모두 영속화한다 — `remember` 호출 시 `type` 파라미터로 `working`, `episodic`, `semantic`, `procedural` 중 하나를 지정하면 된다.\n\n## 살아있는 기억\n\n단순한 저장소가 아니다. Memento의 기억은 살아있다.\n\n중요하게 쓰인 기억은 강화된다. 오래되고 쓸모없어진 기억은 망각 알고리즘에 의해 정리된다. 비슷한 기억들은 벡터 유사도로 서로 연결되어 그래프를 형성한다. 반복 사용하는 절차는 버전 관리되어 `procedural_diff`와 `procedural_rollback`으로 진화를 추적한다. 핵심 맥락은 앵커(Anchor)로 고정되어 새 대화에서도 즉시 복원된다.\n\nAI가 \"기억하는 척\"하는 것이 아니라, 기억을 생성·분류·강화·망각하는 주체로 행동하게 만드는 것 — 그것이 Memento의 목표다.\n\n### 📦 모노레포 구조\n\n이 저장소는 **npm workspaces** 모노레포입니다. `@memento/core`가 도메인·DB·MCP 도구를 담고, `memento-server`가 stdio/HTTP로 이를 노출합니다. 앱이나 스크립트에서 REST로 붙을 때는 `@jee1/memento-client`, OpenClaw 같은 외부 비서에는 `@jee1/memento-assistant`, 에이전트 세션·프로버넌스 계약은 `@memento/agent-integration`이 담당하지만 이는 **내부 전용 패키지**로 npm에 발행되지 않습니다(서버 tarball에 번들). 실험 코드는 `apps/` 아래에 두었습니다.\n\nnpm에 발행되는 패키지는 셋입니다: `memento-mcp-server`(서버), `@jee1/memento-client`, `@jee1/memento-assistant`.\n\n```bash\nnpm i @jee1/memento-client      # REST 클라이언트\nnpm i @jee1/memento-assistant   # 외부 비서용 auto-recall/save SDK\n```\n\n| 경로 | 설명 |\n|------|------|\n| **packages/memento-core** (`@memento/core`) | 도메인·인프라·공유 라이브러리. 진입점: `createMementoCore`, `createToolContext`, `getToolRegistry`, `closeDatabase`. DB 초기화·마이그레이션은 루트에서 `npm run db:init` / `npm run db:migrate`로 실행. |\n| **packages/memento-server** | core를 사용하는 MCP/HTTP 서버. 루트 `npm run dev`, `npm start`, `npm run dev:http` 등으로 실행. |\n| **packages/memento-client** (`@jee1/memento-client`) | 서버 연결용 클라이언트 라이브러리. |\n| **packages/memento-assistant** (`@jee1/memento-assistant`) | 외부 AI 비서용 recall/remember SDK. |\n| **packages/memento-agent-integration** (`@memento/agent-integration`) | 에이전트 통합 계약·어댑터. 내부 전용(`private`), npm 미발행. |\n| **apps/** | 실험용 앱 (예: `experimental-example`은 `@memento/core`를 in-process로 사용). |\n\n상세 구조·빌드·테스트 명령은 [AGENTS.md](AGENTS.md)를 참조하세요.\n\n## 🚀 빠른 시작\n\n> **📦 패키지 매니저**: 이 프로젝트는 **npm**을 사용합니다. `pnpm`이나 `yarn`은 지원하지 않습니다.\n\n### 원클릭 설치 (권장)\n```bash\ncurl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash\n```\n\n### npx 방식 (개발자용)\n\n#### Windows (PowerShell/CMD)\n```powershell\nnpx memento-mcp-server@latest dev\nnpx memento-mcp-server@latest\nnpx memento-mcp-server@latest setup\n```\n\n#### Linux/macOS\n```bash\nnpx memento-mcp-server@latest dev\nnpx memento-mcp-server@latest\nnpx memento-mcp-server@latest setup\n```\n\n> **참고**: `npm exec` 사용 시 명령어를 명시적으로 지정해야 합니다:\n> ```bash\n> npm exec -- memento-mcp-server@latest dev\n> ```\n\n**반복 사용 시 주의**: 매번 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](docs/guides/ko/memento-cli-for-ai.md).\n\n### Claude Code 플러그인 (권장 — 설정 없이 한 번에)\n\n이 저장소 자체가 플러그인 마켓플레이스입니다. MCP 서버 등록과 `recall`→`remember` 사용 습관 skill이 함께 설치됩니다.\n\n```\n/plugin marketplace add jee1/memento\n/plugin install memento@memento\n```\n\n기억 DB는 `${CLAUDE_PLUGIN_DATA}/memory.db`에 저장되어 플러그인을 업데이트해도 유지됩니다. 설치 후 `/plugin` 패널에서 `memento` MCP 서버가 연결됐는지 확인하세요.\n\n### MCP 공식 레지스트리\n\nMemento는 MCP 공식 레지스트리에 `io.github.jee1/memento-mcp-server` 이름으로 등재됩니다. 레지스트리를 읽는 클라이언트·마켓플레이스에서 이 이름으로 찾을 수 있습니다.\n\n```bash\ncurl \"https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jee1/memento-mcp-server\"\n```\n\n등재 메타데이터는 루트 [`server.json`](server.json)에 있고, 정식 릴리스마다 `release.yml`이 npm 배포 후 버전을 맞춰 자동으로 갱신합니다 (pre-release는 등재하지 않습니다).\n\n### Docker 방식 (프로덕션용)\n```bash\ndocker compose -p \"${COMPOSE_PROJECT_NAME:-memento}\" -f docker/docker-compose.dev.yml up -d   # 개발\ndocker compose -p \"${COMPOSE_PROJECT_NAME:-memento}\" -f docker/docker-compose.prod.yml up -d  # 프로덕션\n```\n\n이동된 환경 오버레이를 첫 파일로 사용할 때도 Compose 프로젝트 이름은 기본 `memento`로 유지됩니다. 다른 이름이 필요하면 `COMPOSE_PROJECT_NAME`을 설정하세요.\n\n**Log Issue Monitor**: 운영 로그와 Docker diagnostics를 주기적으로 검사해 반복 오류를 GitHub Issue로 묶어 관리하려면 `docker/docker-compose.issue-monitor.yml` 오버레이를 사용합니다. 자세한 절차: [Log Issue Monitor 운영 가이드](docs/operations/ko/log-issue-monitor.md).\n\n### 소스코드 방식 (개발자용)\n\n```bash\ngit clone https://github.com/jee1/memento.git\ncd memento\nnpm install\nnpm run build\nnpm run db:init\nnpm run db:migrate\nnpm run quick-start\n```\n\n### 다중 에이전트 운영을 위한 HTTP MCP 서버\n\nSQLite는 WAL 모드를 사용해도 동시에 하나의 writer만 허용합니다. 여러 AI Agent가 각각 프로세스로 `remember`/`forget`을 호출하면 `SQLITE_BUSY`가 발생할 수 있으므로, **반드시 MCP 서버 프로세스를 하나만 띄워 DB를 전담**하도록 구성하는 것을 권장합니다.\n\n```bash\nnpm run dev:http                          # 개발 모드 (Hot Reload)\nnpm run build && npm run start:http       # 프로덕션\n```\n\n이 방식으로 `packages/memento-server`의 HTTP MCP 서비스를 띄워 두면, 모든 에이전트는 HTTP/WebSocket 인터페이스를 통해 이 서버에만 접속하고 SQLite writer는 단일 프로세스로 제한됩니다.\n\n#### MCP 클라이언트 설정 예시 (`mcp.json`)\n\n루트에서 `npm run build` 후 서버 실행 파일은 `packages/memento-server/dist/server/http-server.js`에 있습니다.\n\n```json\n{\n  \"clients\": {\n    \"memento\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/memento/packages/memento-server/dist/server/http-server.js\"],\n      \"env\": {\n        \"DB_PATH\": \"/absolute/path/to/data/memory.db\",\n        \"MCP_SERVER_PORT\": \"9001\"\n      },\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http://127.0.0.1:9001/mcp\"\n      }\n    }\n  }\n}\n```\n\n### 상세 설치 가이드\n- [INSTALL.md](INSTALL.md) — 전체 설치 가이드\n- [Cursor MCP 설정 가이드](docs/guides/ko/cursor-mcp-setup.md)\n- [npx 사용자 문제 해결](docs/operations/ko/npx-troubleshooting.md)\n\n## 🔗 외부 AI 비서와 함께 쓰기\n\nOpenClaw / NanoClaw / ZeroClaw 같은 개인 AI 비서가 Memento를 공유 장기 기억 백엔드로 사용할 수 있습니다. 가이드: [docs/integrations/](./docs/integrations/README.md)\n\n`@jee1/memento-assistant` SDK를 사용하면 자동 recall/remember를 코드 두 줄로 붙일 수 있습니다 — [SDK quickstart](./docs/integrations/_shared/sdk-quickstart.md)\n\n## 💡 사용 예시\n\n### AI Agent와의 연동\n```typescript\n// 일화기억으로 학습 내용 저장\nawait client.callTool({\n  name: \"remember\",\n  arguments: {\n    content: \"사용자는 React Hook을 학습했습니다. useState는 상태를 관리하고, useEffect는 사이드 이펙트를 처리합니다.\",\n    type: \"episodic\",\n    tags: [\"react\", \"hooks\", \"javascript\"],\n    importance: 0.8\n  }\n});\n\n// 나중에 관련 기억 검색\nconst results = await client.callTool({\n  name: \"recall\",\n  arguments: {\n    query: \"React Hook은 어떻게 사용하나요?\",\n    limit: 5\n  }\n});\n```\n\n### 의미기억으로 지식 관리\n```typescript\n// 경험에서 증류된 지식을 의미기억으로 저장\nawait client.callTool({\n  name: \"remember\",\n  arguments: {\n    content: \"TypeScript의 제네릭은 타입을 매개변수화하여 재사용 가능한 컴포넌트를 만드는 기능입니다.\",\n    type: \"semantic\",\n    tags: [\"typescript\", \"generics\", \"programming\"],\n    importance: 0.9\n  }\n});\n```\n\n### 절차기억으로 워크플로 보존\n```typescript\n// 반복 작업 절차를 절차기억으로 저장 (버전 관리됨)\nawait client.callTool({\n  name: \"remember\",\n  arguments: {\n    content: \"Docker 컨테이너 빌드 및 배포 절차: 1) Dockerfile 작성 2) docker build 실행 3) docker run으로 테스트 4) 레지스트리에 푸시\",\n    type: \"procedural\",\n    tags: [\"docker\", \"deployment\", \"devops\"],\n    importance: 0.7\n  }\n});\n```\n\n## 🛠️ 사용법\n\n세 가지 접근 방식으로 Memento에 연결할 수 있습니다.\n\n- **mcp.json 설정**: Claude Desktop, Cursor, Claude Code 등 MCP 호스트에 Memento를 등록하는 방식 (코드 불필요)\n- **MCP 프로토콜** (`@modelcontextprotocol/sdk`): 커스텀 에이전트 코드에서 MCP 프로토콜로 직접 연결하는 방식\n- **HTTP API 클라이언트** (`@jee1/memento-client`): TypeScript/JavaScript 코드에서 Memento 서버의 REST API를 프로그래밍 방식으로 사용하는 방식\n\n### 0. mcp.json 설정 (Claude Desktop · Cursor · Claude Code)\n\nMCP 호스트 앱에서 Memento를 사용하려면 설정 파일에 서버 정보를 등록합니다.\n\n#### stdio 모드 (단일 에이전트 / 소스 실행)\n\n`npm run build` 후 아래처럼 등록합니다.\n\n```json\n{\n  \"mcpServers\": {\n    \"memento\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/memento/packages/memento-server/dist/server/index.js\"],\n      \"env\": {\n        \"DB_PATH\": \"/absolute/path/to/data/memory.db\"\n      }\n    }\n  }\n}\n```\n\n> **파일 위치**:\n> - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n> - Cursor: `.cursor/mcp.json` (프로젝트) 또는 `~/.cursor/mcp.json` (전역)\n> - Claude Code: `.claude/mcp.json` (프로젝트) 또는 `~/.claude/mcp.json` (전역)\n\n#### HTTP MCP 모드 (다중 에이전트 공유 서버)\n\n```bash\nnpm run build && npm run start:http   # 기본 포트: 9001 (env.example·Docker와 동일)\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"memento\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:9001/mcp\"\n    }\n  }\n}\n```\n\n> **npx로 실행하는 경우** (소스 빌드 없이):\n> ```json\n> {\n>   \"mcpServers\": {\n>     \"memento\": {\n>       \"command\": \"npx\",\n>       \"args\": [\"memento-mcp-server@latest\"],\n>       \"env\": {\n>         \"DB_PATH\": \"/absolute/path/to/data/memory.db\"\n>       }\n>     }\n>   }\n> }\n> ```\n\n### 1. MCP 프로토콜 연결 (`@modelcontextprotocol/sdk`)\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\n\nconst client = new Client({\n  name: \"my-agent\",\n  version: \"0.1.0\"\n}, {\n  capabilities: { tools: {}, resources: {}, prompts: {} }\n});\n\n// stdio 연결 (단일 프로세스)\nawait client.connect({\n  command: \"node\",\n  args: [\"packages/memento-server/dist/server/index.js\"]\n});\n\n// HTTP MCP 연결 (다중 에이전트 공유 서버)\nawait client.connect({\n  transport: {\n    type: \"http\",\n    url: \"http://127.0.0.1:9001/mcp\"\n  }\n});\n```\n\n```typescript\nconst result = await client.callTool({\n  name: \"remember\",\n  arguments: {\n    content: \"React Hook에 대해 학습했습니다.\",\n    type: \"episodic\",\n    tags: [\"react\", \"hooks\"],\n    importance: 0.8\n  }\n});\n\nconst results = await client.callTool({\n  name: \"recall\",\n  arguments: {\n    query: \"React Hook을 처음 배울 때 알아야 할 것들은?\",\n    filters: { type: [\"episodic\", \"semantic\"], tags: [\"react\"] },\n    limit: 10\n  }\n});\n```\n\n### 2. HTTP API 클라이언트 (`@jee1/memento-client`)\n\n`@jee1/memento-client`는 MCP 프로토콜이 아닌 **HTTP REST API 래퍼**입니다. TypeScript/JavaScript 애플리케이션에서 `/tools/*` 엔드포인트를 직접 호출할 때 사용합니다.\n\n```typescript\nimport { MementoClient } from \"@jee1/memento-client\";\n\nconst client = new MementoClient({\n  serverUrl: \"http://localhost:9001\",\n  apiKey: \"your-api-key\"\n});\n\nawait client.connect();\n\nconst result = await client.remember({\n  content: \"React Hook에 대해 학습했습니다.\",\n  type: \"episodic\",\n  tags: [\"react\", \"hooks\"],\n  importance: 0.8\n});\n\nconst results = await client.recall(\n  \"React Hook을 처음 배울 때 알아야 할 것들은?\",\n  { type: [\"episodic\", \"semantic\"], tags: [\"react\"] },\n  10\n);\n\nawait client.pin(result.memory_id);\nawait client.forget(result.memory_id);\n```\n\n## 🧠 기능\n\n### 🧠 핵심 메모리 관리 (MCP 클라이언트)\n\n- **기억 저장**: `working`, `episodic`, `semantic`, `procedural` 4가지 타입\n- **기억 검색**: 하이브리드 검색 (텍스트 FTS5 + 벡터)\n- **이웃 기억 탐색**: 벡터 유사도 기반 자동 추천\n- **기억 고정**: 중요 기억 pin/unpin\n- **기억 삭제**: 소프트/하드 삭제\n- **앵커 시스템**: 핵심 기억을 앵커로 고정해 다음 대화에서 즉시 컨텍스트 복원\n> **참고**: 앵커 복원, 임베딩 마이그레이션, Episodic → Semantic 변환, 메타 메모리 통계는 MCP 도구가 아니라 HTTP 관리 API로만 제공됩니다.\n\n### 🔍 하이브리드 검색\n\n텍스트와 의미(벡터)를 함께 검색한다. 키워드가 정확히 기억나지 않아도, 개념이 비슷하면 찾아낸다.\n\n- **FTS5 텍스트 검색**: SQLite Full-Text Search\n- **벡터 검색**: sqlite-vec 기반 의미적 유사도 검색\n- **하이브리드 검색**: 두 검색의 결합 (Consolidation Score로 가중치 조정)\n- **다중 임베딩 제공자**: TF-IDF, MiniLM, OpenAI, Gemini 지원\n- **자동 제공자 선택**: 설정 기반 최적 제공자 자동 선택, 실패 시 자동 폴백\n- **태그 기반 필터링**: 메타데이터 기반 검색\n\n### 🧹 망각 정책\n\n기억 시스템이 진짜 유용하려면, 망각도 설계해야 한다. 쌓이기만 하는 기억은 잡음이 된다.\n\n- **망각 알고리즘**: 최근성·사용성·중복 비율 기반 망각 점수 계산\n- **간격 반복**: 중요도와 사용성 기반 리뷰 스케줄링\n- **TTL 관리**: 타입별 수명 관리 (working 48시간, episodic 90일, semantic·procedural 무기한)\n- **자동 정리**: 소프트/하드 삭제 자동화\n\n### 📊 성능 모니터링 (HTTP 관리 API)\n\n> **보안**: HTTP 서버는 브라우저 세션과 헤더 기반 신뢰 경계를 분리합니다. `/auth/session`은 쿠키 기반 브라우저 세션을 시작하고, `/admin`과 `/api`는 브라우저 세션이 필요하며, `/api/v1/quality`, `/api/v1/maintenance`, `/tools`, `/mcp`는 `Authorization: Bearer` 또는 `X-API-Key`가 필요합니다. 자세한 내용: [docs/reference/ko/security.md](docs/reference/ko/security.md)\n\n- **실시간 메트릭**: 데이터베이스, 검색, 메모리 성능 모니터링\n- **실시간 알림**: 30초마다 자동 성능 체크 및 임계값 기반 알림\n- **에러 로깅**: 구조화된 에러 로깅 및 통계 수집\n- **데이터베이스 최적화**: 자동 인덱스 추천 및 생성\n- **캐시 시스템**: LRU + TTL 기반 캐싱\n- **비동기 처리**: 워커 풀 기반 병렬 처리\n\n### 🔗 메모리 그래프 뷰 (브라우저)\n\nHTTP 서버 실행 후 브라우저에서 기억들의 의미적 관계를 그래프로 시각화할 수 있습니다. 전체 관리 흐름은 `/dashboard`에서 여는 편이 가장 안전하며, `/graph`를 직접 열어도 동일한 `/auth/session` 기반 재인증 패널로 세션을 시작하거나 복구할 수 있습니다.\n\n```\nhttp://localhost:9001/dashboard\nhttp://localhost:9001/graph\n```\n\n![Memento Memory Graph View](docs/graph-screenshot.png)\n\n## 📚 문서\n\n전체 문서 목록·KO/EN 매핑: [docs/README.md](docs/README.md)\n\n- [임베딩 서비스 가이드](docs/guides/ko/embedding-service-guide.md)\n- [성능 벤치마크](docs/reference/ko/embedding-performance-benchmark.md)\n- [API 레퍼런스](docs/api/ko/api-reference.md)\n- [설정 가이드](docs/guides/ko/embedding-configuration.md)\n- [Consolidation Score 테스트 가이드](docs/guides/ko/consolidation-quality-testing.md)\n\n## 📋 API 문서\n\n### MCP Tools (등록 22개, 기본 노출 4개)\n\n> **중요**: 서버에는 도구 22개가 등록되어 있지만, `tools/list`에는 기본적으로 **`recall`·`remember`·`memory_injection`·`feedback` 4개만** 노출됩니다(v1.18+). 도구 정의는 세션 내내 클라이언트 컨텍스트를 점유하므로, 늘 켜두는 서버일수록 기본 표면을 줄이는 편이 낫습니다(측정: 5,860 → 2,954 추정 토큰, 49.6% 감소).\n>\n> 나머지 18개는 **등록된 채로 남아 호출은 그대로 됩니다** — 목록에서만 빠집니다. 전부 나열하려면 `MEMENTO_TOOLSET=full`을 설정하세요. 관리/운영성 기능(앵커 복원, 임베딩 마이그레이션, Episodic→Semantic 변환, 메타 메모리 통계)은 여전히 HTTP API로만 제공됩니다.\n\n#### 기본 메모리 관리 (8개)\n| Tool | 설명 | 파라미터 |\n|------|------|----------|\n| `remember` | 기억 저장 | content, type, tags, importance, source, privacy_scope |\n| `recall` | 기억 검색 | query, filters, limit |\n| `feedback` | recall 결과 helpful/not_helpful 피드백 | memory_id, helpful |\n| `pin` | 기억 고정 | memory_id |\n| `unpin` | 기억 고정 해제 | memory_id |\n| `forget` | 기억 삭제 | memory_id, hard |\n| `get_memory_neighbors` | 이웃 기억 탐색 | memory_id, limit |\n| `memory_injection` | 컨텍스트 주입 프롬프트 생성 | query, token_budget |\n\n#### 앵커 시스템 (4개)\n| Tool | 설명 | 파라미터 |\n|------|------|----------|\n| `set_anchor` | 앵커 설정 | memory_id, slot |\n| `get_anchor` | 앵커 조회 | slot |\n| `search_local` | 앵커 주변 검색 | slot, query, limit |\n| `clear_anchor` | 앵커 제거 | slot |\n\n#### 절차 기억 (3개)\n| Tool | 설명 | 파라미터 |\n|------|------|----------|\n| `remember_procedure` | 절차 기억 저장 | content, workflow_name, skill_name, steps 등 |\n| `procedural_diff` | 절차 기억 버전 간 차이 비교 | left_id, right_id |\n| `procedural_rollback` | 절차 기억 이전 버전으로 복원 | current_id, target_version_id |\n\n#### 관계·지식 그래프 (4개)\n| Tool | 설명 | 파라미터 |\n|------|------|----------|\n| `extract_triples` | 본문에서 SPO 트리플 추출 | content 또는 messages |\n| `add_relation` | 기억 간 관계 추가 | source_id, target_id, relation_type |\n| `get_relations` | 관계 조회 | memory_id 등 |\n| `remove_relation` | 관계 삭제 | relation_id |\n\n#### 품질·내보내기 (3개)\n| Tool | 설명 | 파라미터 |\n|------|------|----------|\n| `get_introspection_summary` | 저신뢰·고실패 기억 요약 | — |\n| `get_telemetry_summary` | 검색·메모리 품질 텔레메트리 | period |\n| `export_memories` | 기억 내보내기 | filters 등 |\n\n**HTTP 전용 (MCP에 없음)**: `restore_anchors`, `migrate_embeddings`, `convert_episodic_to_semantic`, `get_meta_memory_stats` — 아래 HTTP 관리 API 참조.\n\n### HTTP 관리 API\n\n> **중요**: 다음 기능들은 MCP 클라이언트에 노출되지 않으며, HTTP API로만 제공됩니다.\n\n#### 메모리 관리\n| 엔드포인트 | 설명 | 메서드 |\n|-----------|------|--------|\n| `/admin/memory/cleanup` | 메모리 정리 | POST |\n| `/admin/memory/convert-episodic-to-semantic` | Episodic → Semantic 변환 | POST |\n| `/admin/memory/meta-stats` | 메타 메모리 통계 조회 | GET |\n| `/admin/memory/review-candidates` | 기억 리뷰 후보 목록 | GET |\n| `/admin/memory/items/:memory_id` | 단일 기억 프리뷰(JSON, 대시보드 등) | GET |\n| `/admin/memory/review-candidates/:id/review` | 기억 리뷰 후보 처리 | POST |\n| `/admin/memory/review-candidates/:id/dismiss` | 기억 리뷰 후보 기각 | POST |\n| `/admin/stats/forgetting` | 망각 통계 조회 | GET |\n\n#### 개인 지식 Agent\n| 엔드포인트 | 설명 | 메서드 |\n|-----------|------|--------|\n| `/api/v1/agent/personal:run` | 한 턴 실행, 지식 후보 반환(저장 없음) | POST |\n| `/api/v1/agent/personal:persist-approved` | 승인된 후보만 `remember`로 저장 | POST |\n\n사용 절차: [개인 지식 에이전트 HTTP 서버 런타임 사용법](docs/guides/ko/personal-knowledge-agent-mvp.md#http-서버-런타임-사용법)\n\n#### 앵커 관리\n| 엔드포인트 | 설명 | 메서드 |\n|-----------|------|--------|\n| `/admin/anchors/restore` | 앵커 복원 | POST |\n\n#### 임베딩 관리\n| 엔드포인트 | 설명 | 메서드 |\n|-----------|------|--------|\n| `/admin/embeddings/migrate` | 임베딩 마이그레이션 | POST |\n\n#### 성능 모니터링\n| 엔드포인트 | 설명 | 메서드 |\n|-----------|------|--------|\n| `/admin/stats/performance` | 성능 통계 조회 | GET |\n| `/admin/alerts/performance` | 성능 알림 조회 | GET |\n\n#### 에러 관리\n| 엔드포인트 | 설명 | 메서드 |\n|-----------|------|--------|\n| `/admin/stats/errors` | 에러 통계 조회 | GET |\n| `/admin/errors/resolve` | 에러 해결 | POST |\n\n#### 데이터베이스 관리\n| 엔드포인트 | 설명 | 메서드 |\n|-----------|------|--------|\n| `/admin/database/optimize` | 데이터베이스 최적화 | POST |\n\n**기타 HTTP admin**: 배치 상태/실행(`/admin/batch/*`, `jobType`에 `memory_review_candidates` 포함), 성능 메트릭·알림(`/admin/performance/*`), 관계 추출·조회·시각화(`/admin/relations/*`) 등은 [docs/api/ko/api-reference.md](docs/api/ko/api-reference.md)를 참고하세요.\n\n### Resources\n\n| Resource | 설명 |\n|----------|------|\n| `memory/{id}` | 단일 기억 상세 정보 |\n| `memory/search?query=...` | 검색 결과 캐시 |\n\n## 🔧 설정\n\n### 환경 변수\n\n| 변수 | 기본값 | 설명 |\n|------|--------|------|\n| `NODE_ENV` | development | 실행 환경 |\n| `PORT` / `MCP_SERVER_PORT` | 9001 (http-server fallback) | HTTP/MCP 서버 포트 (`env.example`·Docker 권장: 9001) |\n| `DB_PATH` | ./data/memory.db | 데이터베이스 경로 |\n| `LOG_LEVEL` | info | 로그 레벨 |\n| `OPENAI_API_KEY` | - | OpenAI API 키 (선택사항) |\n| `GEMINI_API_KEY` | - | Gemini API 키 (선택사항) |\n| `EMBEDDING_PROVIDER` | minilm | 임베딩 제공자 (tfidf, lightweight, minilm, openai, gemini) |\n| `CONSOLIDATION_SCORE_ENABLED` | false | Consolidation Score System 활성화 여부 |\n| `CONSOLIDATION_TEST_SEED_PATH` | ./data/consolidation-seed.json | 테스트 Seed 데이터 파일 경로 |\n| `CONSOLIDATION_BASELINE_PATH` | ./data/consolidation-baseline.json | Baseline 스냅샷 저장 경로 |\n| `CONSOLIDATION_TEST_ITEM_COUNT` | 100 | 벤치마크 테스트 데이터 크기 |\n| `CORS_ALLOWED_ORIGINS` | (비어 있음) | CORS 허용 오리진 (쉼표 구분, 비어 있으면 크로스 오리진 미허용) |\n| `ENABLE_PII_MASKING` | true | PII 마스킹 활성화 ([docs/reference/ko/security.md](docs/reference/ko/security.md) 참고) |\n| `MEMORY_REVIEW_IMPORTANCE_THRESHOLD` | `0.7` | 기억 리뷰 후보 최소 importance (0~1) |\n| `MEMORY_REVIEW_STALE_DAYS` | `14` | 기억 리뷰 후보 최소 stale 일수 (정수 ≥ 1) |\n| `MEMORY_REVIEW_MAX_CANDIDATES` | `50` | 기억 리뷰 후보 최대 개수 (정수 ≥ 1) |\n| `MEMORY_REVIEW_MAX_BACKLOG` | `500` | pending 후보가 이 수 이상이면 신규 선정을 건너뜀 (`0`: 비활성화) |\n| `MEMORY_REVIEW_CANDIDATE_TTL_DAYS` | `30` | 이 일수보다 오래된 pending 후보를 배치 실행 전에 만료 (`0`: 비활성화) |\n| `MEMORY_REVIEW_CANDIDATES_INTERVAL_MS` | `86400000` | 배치 스케줄 간격(ms), 최소 `60000` |\n| `MEMORY_REVIEW_CANDIDATE_DUE_DAYS` | `14` | 배치가 `due_at`에 더하는 일 수 (1~366) |\n\n> **참고**: 망각 TTL, LLM/Ollama, 검색 한도 등 추가 변수는 `env.example`을 참고하세요.\n\n### 망각 정책 설정\n\n```bash\nFORGET_THRESHOLD=0.6\nSOFT_DELETE_THRESHOLD=0.6\nHARD_DELETE_THRESHOLD=0.8\n\nTTL_SOFT_WORKING=2\nTTL_SOFT_EPISODIC=30\nTTL_SOFT_SEMANTIC=180\nTTL_SOFT_PROCEDURAL=90\n```\n\n## 🧪 테스트\n\n```bash\nnpm run test\n\nnpm run test:ci:core\nnpm run test:ci:server\nnpm test -w @jee1/memento-client\nnpm run benchmark:consolidation-quality\n\nnpm run test -- --watch\nnpm run test -- --coverage\n```\n\n공개 데이터셋(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](docs/guides/ko/benchmark-datasets.md)에 있고, 프로덕션 검색이 단순 FTS 베이스라인을 넘지 못한 상태라 대외 수치로 쓰지 않습니다.\n\n## 📚 개발자 가이드라인\n\n- **프로젝트 구조**: npm workspaces 모노레포 — `packages/memento-core`, `packages/memento-server`, `packages/memento-client`, `apps/*`. 상세: [AGENTS.md](AGENTS.md)\n- **빌드/테스트**: `npm run build`(core→server→client), `npm run dev`·`npm start`(서버), `npm run db:init`·`npm run db:migrate`(DB), `npm test`\n- **코딩 스타일**: Node.js ≥ 24, TypeScript ES 모듈, 2칸 들여쓰기\n- **테스트**: Vitest 기반. 단위·스펙은 `packages/*/src/**/*.spec.ts`, 워크스페이스 수준 통합 스펙은 루트 `tests/`\n- **커밋/PR**: Conventional Commits, 한국어 컨텍스트 포함\n\n## 📊 성능 지표\n\n### 기본 성능\n- **데이터베이스**: 평균 쿼리 시간 0.16-0.22ms\n- **검색**: 0.78-4.24ms (캐시 효과로 개선)\n- **메모리 사용량**: 11-15MB 힙\n- **동시 연결**: 최대 1000개\n\n### 임베딩 제공자 비교\n\n#### 무료 제공자 (로컬 처리)\n- **TF-IDF**: 512차원, 극도로 빠름 (0.82ms), 낮은 메모리 (4.48MB)\n- **MiniLM**: 384차원, 균형잡힌 성능, 다국어 지원\n\n#### 유료 제공자 (클라우드 API)\n- **OpenAI**: 1536차원, 최고 성능, 높은 정확도\n- **Gemini**: 768차원, 고성능, 다국어 지원\n\n**자동 선택 순서**: 명시적 요청 → `.env`의 `EMBEDDING_PROVIDER` → OpenAI(1) → Gemini(2) → MiniLM(3) → TF-IDF(4). 상위 제공자 실패 시 자동 폴백.\n\n## 🏗️ 아키텍처 여정\n\nMemento는 개인용 로컬 서버로 시작해, 팀 협업을 거쳐, 조직 규모의 메모리 플랫폼으로 성장하도록 설계되어 있다.\n\n**M1: 개인용 (현재)** — 지금 사용할 수 있는 형태다. SQLite 임베디드, FTS5 + sqlite-vec 인덱스, 로컬 실행. **인증**: 브라우저 세션 + 헤더 기반 분리 신뢰 모델(`/auth/session` 쿠키 세션, `/admin`·`/api` 브라우저 세션 요구, `/tools`·`/mcp`는 Bearer/API-Key 요구). MCP 도구 22개 등록·기본 노출 4개(`MEMENTO_TOOLSET=full`로 전체), 관리 기능은 HTTP API로 분리.\n\n**M2: 팀 협업 (계획)** — SQLite 서버 모드, API Key 인증, Docker 단일 컨테이너. 여러 팀원이 하나의 기억 백엔드를 공유한다.\n\n**M3: 조직 (계획)** — PostgreSQL + pgvector, JWT 인증, Docker Compose. 수백 명의 에이전트가 조직의 기억을 공유한다.\n\n## ❓ 자주 묻는 질문\n\n### Q: Memento는 어떤 AI Agent와 호환되나요?\nA: MCP(Model Context Protocol)를 지원하는 모든 AI Agent와 호환됩니다. Claude, GPT-4, Gemini 등과 연동 가능합니다.\n\n### Q: 기억 데이터는 어디에 저장되나요?\nA: 기본적으로 로컬 SQLite 데이터베이스(`./data/memory.db`)에 저장됩니다.\n\n### Q: OpenAI API 키가 필요한가요?\nA: 선택사항입니다. API 키 없이도 **TF-IDF** 또는 **MiniLM** 기반 임베딩으로 동작합니다. 더 정확한 검색을 원한다면 OpenAI 또는 Gemini API 키를 설정하세요.\n\n### Q: 기억 용량에 제한이 있나요?\nA: SQLite 데이터베이스 제한에 따라 달라집니다. 일반적으로 수백만 개의 기억을 저장할 수 있습니다.\n\n### Q: 다른 사용자와 기억을 공유할 수 있나요?\nA: 현재 M1은 개인용입니다. M2부터 팀 협업 기능이 추가될 예정입니다.\n\n### Q: 기억이 자동으로 삭제되나요?\nA: 망각 정책에 따라 자동으로 삭제됩니다. 중요한 기억은 `pin` 기능으로 고정할 수 있습니다.\n\n## 🤝 기여하기\n\nMemento 프로젝트에 기여하고 싶으신가요? 자세한 가이드: [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### 빠른 기여 시작\n1. **Fork** the Project\n2. **Create** your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. **Commit** your Changes (`git commit -m 'feat: add some AmazingFeature'`)\n4. **Push** to the Branch (`git push origin feature/AmazingFeature`)\n5. **Open** a Pull Request\n\n### 개발 환경 설정\n```bash\ngit clone https://github.com/your-username/memento.git\ncd memento\nnpm install\nnpm run dev\nnpm run test\n```\n\n### 기여 방법\n- 버그 리포트: [GitHub Issues](https://github.com/jee1/memento/issues)\n- 기능 제안: 새로운 아이디어를 제안해주세요\n- 문서 개선: 문서를 더 명확하게 만들어주세요\n- 코드 기여: 새로운 기능이나 버그 수정을 도와주세요\n\n## 📄 라이선스\n\n이 프로젝트는 [MIT License](LICENSE) 하에 배포됩니다. `package.json`의 `\"license\": \"MIT\"` 와 동일합니다.\n\n## 📞 지원\n\n- 이슈 리포트: [GitHub Issues](https://github.com/jee1/memento/issues)\n- 문서: [Wiki](https://github.com/jee1/memento/wiki)\n- 개발자 가이드: [docs/guides/ko/developer-guide.md](docs/guides/ko/developer-guide.md)\n- API 참조: [docs/api/ko/api-reference.md](docs/api/ko/api-reference.md)\n\n## 🙏 감사의 말\n\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [OpenAI](https://openai.com/)\n- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)\n- [Express](https://expressjs.com/)\n- [Vitest](https://vitest.dev/)\n- [TypeScript](https://www.typescriptlang.org/)\n",
  "bytes": 22916,
  "sha": "29eaa87740fb0b042327d96c9b82d844d6a4ba95f41f98a5c6365a3e802e6aae",
  "repo_slug": "jee1/memento",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jee1_memento_mcp_server_a5d859cc/readme"
}