Memento-cmp

매일 아침 기억이 리셋되는 신입직원을 상상해보라. 어제 가르친 것도, 지난주 함께 해결한 문제도, 취향도 전부 까먹는다. AnchorMind는 이 신입에게 기억을 심어준다.

AnchorMind는 MCP(Model Context Protocol) 기반 에이전트 장기 기억 서버다. 세션이 종료되어도 중요한 사실, 결정, 에러 패턴, 절차를 유지하고 다음 세션에서 복원한다.

이 프로젝트는 memento-mcp라는 이름으로 시작했다. 기억을 다루는 프로젝트에 잘 어울리는 이름이라고 지금도 생각하지만, 같거나 비슷한 이름의 프로젝트가 많아 AnchorMind로 바꿨다. 흘러가는 대화 속에서 남길 가치가 있는 기억을 닻처럼 붙들어 고정한다는 뜻이며, 세션이 끝나도 유실되지 않는 이 시스템의 앵커 파편(anchor fragment) 개념과도 맞닿아 있다.

단순한 기억의 도서관이 아니다. 피드백이 쌓이면 연결이 강해지고, 경험이 반복되면 패턴이 추상화되고, 세션이 이어지면 이야기가 생긴다. 기억하는 AI가 아니라 경험으로 성장하는 AI를 지향한다.

[!TIP] 설치·설정을 직접 다루기 부담스럽다면 Claude Code·Cursor·Codex 같은 AI 어시스턴트에 다음 한 문장을 전달하면 된다.

"anchormind 저장소를 내 환경에 설치하고,docs/INSTALL.md와SKILL.md를 읽어 권장 설정을 적용한 뒤 동작을 검증해 줘."

의존성 설치,.env구성, MCP 등록, 헬스 체크까지 AI가 안내한다. 자세한 위임 절차는docs/INSTALL.md참고.

[세션 1] 사용자: "우리 프로젝트는 PostgreSQL 15를 쓰고, 테스트는 Vitest로 돌려" → AI가 remember 호출 → 파편 2개 저장 [세션 2 — 다음 날] → AI가 context 호출 → "PostgreSQL 15 사용", "Vitest 테스트" 자동 복원 사용자: "테스트 어떻게 돌리더라?" → AI가 recall 호출 → "Vitest로 테스트 실행" 파편 반환 → AI: "이 프로젝트는 Vitest를 사용합니다. npx vitest로 실행하세요."

필수: Node.js 20+, PostgreSQL (pgvector 확장)

cp .env.example.minimal .env # .env 값을 편집한 뒤 셸에 반영 export $(grep -v '^#' .env | grep '=' | xargs) npm install npm run migrate node server.js

OpenAI API 없이 로컬 임베딩을 사용하려면.env에EMBEDDING_PROVIDER=transformers를 추가한다. 기동 시Xenova/multilingual-e5-small모델을 자동으로 다운로드한다. 단, OpenAI 임베딩으로 이미 저장된 데이터와 혼용하면 차원이 불일치하므로 새로 마이그레이션된 DB에서만 사용할 것.

cd ~/memento-mcp git pull origin main npm install npm run migrate # 서비스 재시작 (systemd / pm2 / docker 등 환경에 맞게)

- npm run migrate는.env의 DB 설정을 자동으로 사용한다.DATABASE_URL수동 지정 불필요.
- pgvector 스키마는 자동 감지된다.PGVECTOR_SCHEMA설정은 대부분 불필요.

claude mcp addCLI로 등록한다 (HTTP 타입 MCP 서버는settings.json에 수동 기재해도 인식되지 않는다).

claude mcp add memento http://localhost:57332/mcp \ --transport http \ --scope user \ --header "Authorization: Bearer YOUR_ACCESS_KEY"

claude mcp list # memento: http://localhost:57332/mcp (HTTP) - ✓ Connected

프로젝트 단위로 공유하려면 저장소 루트의.mcp.json에 기재한다. 상세 설정은Claude Code Configuration참조.

# 원격 서버에서 recall (환경변수 방식) MEMENTO_CLI_REMOTE=https://example.com/mcp MEMENTO_CLI_KEY=mmcp_xxx memento-mcp recall "query" # 원격 서버에서 recall (플래그 방식) memento-mcp recall "query" --remote https://example.com/mcp --key mmcp_xxx # 표 형식 출력, 결과 5건 memento-mcp recall "query" --format table --limit 5 # idempotency key로 중복 저장 방지 memento-mcp remember "내용" --topic 프로젝트명 --idempotency-key k1

--format table|json|csv출력 형식 선택, 14개 서브명령에--help/-h지원. 자세한 플래그는docs/cli.md.

{ "fragments": [...], "_meta": { "searchEventId": 1234, "hints": [ { "signal": "consider_context", "suggestion": "...", "trigger": "recall" } ], "suggestion": { "code": "empty_result_no_context", "message": "..." }, "serverTime": { "iso" : "2026-05-15T06:32:11.000Z", "epoch_ms" : 1747291931000, "display_kst": "2026년 5월 15일 (목) 15:32", "timezone" : "Asia/Seoul" } } }

remember/amend/forget의 성공 응답에는 일정 확률로_meta.hints에feedback_sampled신호가 실린다. 힌트의args를 그대로tool_feedback에 전달해 결과를 평가하면 된다(MEMENTO_FEEDBACK_SAMPLING=false로 비활성화).

remember/link/forget/amend는dryRun: true파라미터로 부작용 없이 예상 결과만 반환한다. 모든 응답에X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Resource헤더가 포함되며 master key 또는 limit=null 설정 시 헤더를 생략한다.recall은fields배열로 반환 필드를 17개 화이트리스트 범위로 제한할 수 있다.remember/batchRemember는idempotencyKey파라미터로 같은 key_id 범위 내 중복 저장을 방지한다(최대 128자).remember/batchRemember항목 /amend의content는 4000자를 초과하면 JSON-RPC -32602 에러로 거부된다. 위 파편 유형별 저장 절삭(1000자/300자)과는 별개로 그보다 앞단에서 적용되는 수신 게이트이며,batchRemember는 초과 항목만 실패 처리하고 나머지 배치는 그대로 진행한다.

- RBAC default-deny:TOOL_PERMISSIONS맵에 없는 도구명은 권한과 무관하게 즉시 거부.
- 테넌트 격리: forget / amend / link / fragment_history는 SQL 레벨key_id조건으로 타 테넌트 파편 접근 불가. "없음"과 "권한 없음"을 동일 메시지로 처리하여 존재 여부 노출 방지.
- injectSessionContext: 클라이언트가 전송한_keyId/_permissions등 내부 필드를 서버 인증 결과로 재주입하여 세션 컨텍스트 위조 차단.
- Admin rate limit:/auth,/keysPOST,/importPOST에 IP 기반 rate limit.
- OpenAPI:GET /openapi.json엔드포인트(ENABLE_OPENAPI=true). master key는 전체 경로, API key는 permissions 필터 스펙 반환.

선택적 설명 가능성, advisory 링크 무결성, 극성 충돌 탐지, 정책 규칙 soft gating. 9 core 모듈 + 5 규칙 파일. 모든 플래그 기본 비활성.

- ProactiveRecall:remember()시 키워드 오버랩 기반 유사 파편 자동 링크.
- CaseRewardBackprop: case verification 이벤트 시 증거 파편 importance 자동 역전파.
- SearchParamAdaptor: 사용 패턴 기반 검색 임계값 자동 최적화.
- CBR(Case-Based Reasoning):recall(caseMode=true)로 유사 사례의 goal → events → outcome 흐름을 검색하여 과거 해결 패턴 재활용.
- depth 필터: Planner/Executor 역할별 검색 깊이 제어("high-level"/"detail"/"tool-level").
- recall 응답key_id: 반환 파편에 소유 테넌트 식별자 포함.
- Reconsolidation:tool_feedback기반fragment_linksweight/confidence 실시간 갱신(ENABLE_RECONSOLIDATION=true).
- Spreading Activation:recall(contextText=...)전달 시 대화 맥락 기반 관련 파편 ema_activation 선제 활성화(ENABLE_SPREADING_ACTIVATION=true).

fragments.id는frag-{16자 hex}text 형식이다. UUID가 아니므로 외부에서 ID를 생성하거나 파싱할 때 주의한다.

/metrics엔드포인트가 Prometheus 호환 형식으로 메트릭을 노출한다. 수집·시각화는 사용자가 자유롭게 구성한다.

AnchorMind가 주입하는 기억 파편은 시스템 프롬프트보다 우선순위가 낮다. "PostgreSQL 15를 쓴다"같은 사실 기억은 잘 작동하지만, "테스트 작성 시 반드시 Given-When-Then 패턴을 쓸 것"같은 행동 규칙은 시스템 프롬프트와 충돌하면 무시될 수 있다.

행동 규칙은 CLAUDE.md, AGENTS.md, 훅(hooks), 스킬(skills) 등 우선순위가 높은 채널에 설정하는 것을 권장한다.

검색은 6개 문항 유형 중 5개에서 80% 이상 recall을 달성한다. 다만 검색 recall(88.3%)과 QA 정답률(45.4%) 사이에 큰 gap이 존재한다. 이는 검색된 파편에서 정답을 합성하는 reader 단계의 한계로, multi-session 추론과 시간축 추론에서 특히 두드러진다.

AnchorMind는 사실 기억(fact cache)에 최적화되어 있다. 전후관계가 중요한 경우:

- episode유형으로 서사를 저장하면 "왜 그런 결정을 했는지"까지 복원 가능
- contextSummary를 함께 저장하면 recall 시 맥락이 함께 반환됨
- 메인 메모리 시스템(MEMORY.md 등)과 병행하여 사실 검색은 AnchorMind, 맥락 복원은 메인 메모리로 역할 분담하는 이원화 구조도 효과적

- Claude Code / Cursor / Windsurf 등 AI 에이전트를 매일 쓰는 개발자
- 세션마다 같은 설명을 반복하는 게 짜증나는 사람
- AI에게 내 프로젝트 맥락을 기억시키고 싶은 사람

lib/ memory/ read/ # FragmentSearch, SearchScope, SearchSideEffects, CaseRecall 등 write/ # MemoryRememberer, BatchRememberProcessor 등 link/ # MemoryLinker, ReconsolidationEngine 등 consolidate/ # MemoryConsolidator embedding/ # EmbeddingWorker, EmbeddingCache, MorphemeIndex signals/ # SpreadingActivation, CaseRewardBackprop 등 processors/ # facade — MemoryRecaller, MemoryReflector 등 storage/ # PgVectorStore(기본), SqliteVecStore(스텁, 미구현) 어댑터 계층 llm/ # dispatchChain, provider 구현체 symbolic/ # SymbolicVerificationLayer (opt-in) docs/ getting-started/ # 플랫폼별 설치 가이드 operations/ # 운영 가이드 (llm-providers, symbolic-hard-gate 등) features.md # 모듈 ledger configuration.md # 환경변수 전체 레퍼런스

- /health: DB, Redis, pgvector, 워커 상태를 종합 점검. 부분 장애 시 degraded 응답.
- Rate Limiting: API 키당 100/분, IP당 30/분. 환경변수로 조정 가능.
- 워커 복구: 임베딩/평가 워커가 에러 시 지수 백오프(1s→60s)로 자동 재시도.
- Graceful Shutdown: SIGTERM 시 진행 중 워커 완료 대기(30초) 후 세션 auto-reflect 실행.
- OAuth 엔드포인트: 인증 실패 시WWW-Authenticate헤더를 반환하여 OAuth 클라이언트가 자동으로 인증 흐름을 시작할 수 있다. 세션 TTL 기본값은 240분이다.
- 마이그레이션 lint:npm run lint:migrations로 번호 충돌 및 규약 위반을 커밋 전 검사.
- 운영 가이드:docs/operations/— LLM provider 체인, symbolic hard gate, agent worktree, upstream porting 등.
- 외부 노출 점검:docs/operations/maintenance.md의 "외부 노출 점검" 절차로 listen 주소, 인증 키, Origin allowlist 상태를 확인.

- L1 Redis 캐시는 API 키 기반 격리만 지원한다. multi-agent 환경에서 에이전트 간 격리는 L2/L3에서 적용된다.
- 자동 품질 평가는 decision, preference, relation 유형만 대상이다. fact, procedure, error는 평가 큐에서 제외된다.
- MEMENTO_ACCESS_KEY를 설정하지 않으면 인증이 비활성화된다. 외부 노출 환경에서는 반드시 설정할 것.
- ALLOWED_ORIGINS — 브라우저 기반 MCP 클라이언트 화이트리스트. 미설정 시 모든 Origin을 허용한다. 외부 노출 환경에서는MCP_STRICT_ORIGIN=true와 함께 실제 사용하는 브라우저 Origin만 등록할 것. 데스크탑/CLI/IDE 확장(Claude Code, Cursor, Windsurf, Continue, Cline, Zed, gemini CLI 등)은 Origin 헤더를 보내지 않으므로 화이트리스트 불필요. 브라우저 후보: claude.ai, claude.com, chatgpt.com, chat.openai.com, copilot.microsoft.com, gemini.google.com, aistudio.google.com,www.perplexity.ai, cursor.com, codeium.com, windsurf.com, sourcegraph.com, typingmind.com (실제 호출하는 것만 선별).
- ADMIN_ALLOWED_ORIGINS — Admin UI 호출 origin 화이트리스트. 미설정 시 모든 Origin을 허용한다. 외부 노출 환경에서는 관리 콘솔 Origin을 명시하거나 리버스 프록시/방화벽에서 접근을 제한할 것.
- TRUST_PROXY_HOPS — 신뢰 가능한 리버스 프록시 hop 수. 미설정 시 기존 동작 유지(XFF 첫 항목). 직접 노출 시 0, 단일 프록시 뒤에서는 1.
- OAUTH_TRUSTED_ORIGINS — 동의 자동 승인 대상 origin 화이트리스트. 동일 origin에서 여러 앱을 호스팅하면 OAUTH_ALLOWED_REDIRECT_URIS의 전체 URI 매칭 사용을 권장.

Real-time stock heatmaps and investment tools delivered as interactive React components.