Releases

업그레이드 주의

• -데이터베이스 마이그레이션은 없다. git pull, npm install, 서비스 재시작이면 된다.
• -절차–오류 연결 제안(_meta.link_suggestions)의 fromId와 toId가 절차→오류에서 오류→절차로 뒤집힌다. 제안을 그대로 link에 넘기던 호출은 이제 규약에 맞는 방향으로 연결된다.
• -resolved_by로 해결된 에러의 중요도를 0.5로 내리는 처리가 시작점이 error인 호출에서 동작한다. 이전에는 이 방향에서 발동하지 않았다.
• -해결책 → 에러 방향으로 저장된 기존 resolved_by는 바꾸지 않는다. graph_explore(절차)와 reconstruct_history의 미해결 판정이 두 방향을 모두 읽는다.

Added

• -reflect 연결 제안의 meta.relationHint. 오류–결정 후보(caused_by)에 link 규약에 맞는 오류→결정 resolved_by 연결(fromId, toId, relationType)을 함께 싣는다. 후보의 기존 키는 바뀌지 않는다.

Changed

• -resolved_by의 방향을 "에러(fromId) → 해결책(toId)"로 통일했다. 절차–오류 연결 제안과 자동 연결의 fromId와 toId가 절차→오류에서 오류→절차로 바뀐다. 해결책 → 에러 방향으로 저장된 이전 연결은 그대로 두고 getRCAChain(절차)과 미해결 판정이 계속 읽는다.

Fixed

• -link가 resolved_by를 걸 때 해결된 에러의 중요도를 0.5로 내리는 처리가 도착점이 error일 때만 동작하던 문제. 규약 방향(시작점이 error)에서는 발동하지 않았다. 시작점이 error이면 시작점을, 이전 방향이면 도착점의 error를 내린다.
• -케이스 이벤트의 resolved_by 간선이 해결 이벤트에서 에러 이벤트 방향으로 기록되어, reconstruct_history의 미해결 브랜치 판정이 에러를 해결된 것으로 보지 못하던 문제. 간선을 에러에서 해결 이벤트 방향으로 기록하고, 판정은 어느 방향의 간선이든 해결로 본다.
• -graph_explore(getRCAChain)가 해결책 → 에러 방향으로 저장된 절차 resolved_by를 에러에서 시작할 때 찾지 못하던 문제.

업그레이드 주의

• -마이그레이션 migration-064(fragment_segment 표)가 포함된다. 운영 반영 직전에 scripts/ops/backup.sh --label pre-migration으로 백업을 만든다. 구간 임베딩은 기본 꺼짐이라 MEMENTO_SEGMENT_EMBEDDING_ENABLED와 MEMENTO_SEGMENT_SEARCH를 켜기 전에는 검색 결과가 달라지지 않는다.
• -reflect의 _meta.link_suggestions가 기본으로 줄어든다. 키워드 겹침 0.4 미만 후보는 만들지 않고 그룹당 3개까지만 싣는다. 이전 동작은 MEMENTO_LINK_SUGGEST_MIN_OVERLAP=0과 MEMENTO_LINK_SUGGEST_MAX=0으로 되돌린다.
• -의존성 sharp override가 0.35.5로 올라간다. git pull 뒤 npm install을 실행하고 서비스를 재시작한다.

Added

• -reflect 연결 제안(_meta.link_suggestions)에 최소 키워드 겹침 기준(MEMENTO_LINK_SUGGEST_MIN_OVERLAP, 기본 0.4), 1위와 2위 후보의 최소 점수 차이(MEMENTO_LINK_SUGGEST_MIN_MARGIN, 기본 0), 그룹당 상한(MEMENTO_LINK_SUGGEST_MAX, 기본 3)을 추가했다. 제안 항목에 meta(score, margin, signals, scoreVersion)가 붙고, 상한으로 빠진 개수는 _meta.link_suggestions_omitted로 알린다. 후보는 같은 그룹(workspace, case_id, topic)의 파편끼리만 짝짓고 점수 동률은 id 순으로 정한다. 키워드 겹침은 소문자·중복 제거한 집합으로 센다. 기준을 0으로 두면 이전처럼 겹침이 없어도 가장 높은 후보를 제안한다.
• -구간(세그먼트) 임베딩(옵트인, 기본 꺼짐). 400자를 넘는 파편을 300자 창으로 나눠 구간별 벡터를 fragment_segment(migration-064)에 두고, L3 시맨틱 검색에서 조각별 최대 유사도(감쇠 0.95, 영향 조각 상한 10)를 본문 후보에 합친다. 최대 1000자 본문 속 곁다리 언급이 본문 벡터에 희석되어 놓치던 근거를 회수한다. 환경변수 MEMENTO_SEGMENT_EMBEDDING_ENABLED, MEMENTO_SEGMENT_SEARCH, MEMENTO_SEGMENT_MIN_CHARS, MEMENTO_SEGMENT_DECAY, MEMENTO_SEGMENT_ADOPT, MEMENTO_SEGMENT_SEARCH_TIMEOUT_MS, MEMENTO_SEGMENT_RPM. 키/에이전트/워크스페이스 열 없이 부모 fragments로 격리한다. 기존 파편은 scripts/backfill-fragment-segments.js로 채운다.
• -RERANKER_WINDOW(기본 30)와 RERANKER_TOP_K(기본 15) 환경변수. 리랭커가 재정렬하는 RRF 상위 후보 수와 재정렬 뒤 남기는 개수를 설정으로 뺐다. 기본값은 기존 동작과 같다.
• -MEMENTO_RECALL_MIN_SIM_CEIL 환경변수. SearchParamAdaptor.getMinSimilarity가 반환하는 적응형 임계값에 옵트인 상한을 강제한다. 학습 규칙이 병합 결과 건수(평균 8 초과면 상승)를 기준으로 해서 값이 CLAMP_MAX(0.60)에 고착될 수 있는 배포를 위한 것이다. 하한과 함께 설정하면 하한이 우선한다. 미설정 시 기존 동작 그대로.
• -구간 임베딩 워커가 한 회차 안의 파편을 MEMENTO_SEGMENT_CONCURRENCY(기본 4, 1~32)개씩 동시에 임베딩한다. 직렬 처리는 임베딩 백엔드가 놀아도 처리량이 막혔다. 임베딩 호출은 EMBEDDING_CONCURRENCY와 EMBEDDING_SEM_WAIT_MS를 함께 쓰므로 동시성을 올리면 두 값도 맞춰 올린다.
• -본문 절삭 가시화. 300자(episode 1000자)를 넘어 잘린 본문은 응답의 content_truncated(original_length, stored_length)와 validation_warnings의 contentTruncated로 알린다. batch_remember는 항목별 results[].content_truncated와 최상위 truncated_count(1건 이상일 때만)를 돌려주고, remember의 dryRun 응답에도 같은 필드가 붙는다. 절삭이 없으면 응답은 달라지지 않는다. contentTruncated는 symbolic_hard_gate의 차단 대상이 아니다.
• -서버 instructions 상단에 저장 계약(본문 상한 300/1000자, 초과분 폐기, 입력 상한 4000자) 블록. 수치는 lib/memory/contentGuard.js의 상수에서 만든다.

Changed

• -벤치마크 리포트(docs/benchmark.md)와 README의 LongMemEval-S 수치를 bge-m3, 구간 검색 켬 기준 최신 측정값으로 바꿨다.
• -도구 스키마와 API 문서의 content 설명을 "300자 이내 권장"에서 "초과분 폐기"로 바꿨다. 절삭 동작은 변하지 않는다. 4000자는 episode 전용이 아니라 content 필드의 공통 입력 상한이다.

Fixed

• -sharp override를 0.35.5로 올려 권고 GHSA-wq5f-xc86-pv6w(librsvg 취약점)를 해소했다.
• -본문에 특수 토큰 문자열(<|endoftext|> 등)이 있으면 토큰 수 계산이 예외를 던져 batch_remember가 그 항목을 거부하던 문제. 특수 토큰도 일반 텍스트로 센다.
• -리랭커가 재정렬한 파편이 재정렬되지 않은 파편(연결 파편, 재정렬 창 밖) 아래로 밀리던 문제. 재정렬 점수와 복합 점수의 척도 차이를 보정해 재정렬된 파편이 항상 위에 온다.

업그레이드 주의

• -Node.js 최소 버전을 20에서 22로 올렸다. 런타임 의존성 openai(7.x)가 Node 22 이상을 요구해서 Node 20에서는 npm ci --engine-strict가 EBADENGINE으로 실패했다. Node 20을 쓰고 있다면 22 이상으로 올린 뒤 npm ci를 다시 실행한다. Docker 이미지(Node 24)와 CI는 이미 22 이상이다.
• -데이터베이스 마이그레이션은 없다. git pull, npm install, 서비스 재시작이면 된다.

Added

• -config/env-access.js와 npm run env-access. 중앙 모듈(lib/config.js, config/) 밖에서 process.env를 읽는 지점을 구문 분석으로 찾아 startup, runtime, cli로 분류하고 대장과 대조한다. 등록되지 않은 접근, 코드에 없는 등록, 분류가 어긋난 등록은 tests/structure/env-access.test.js가 실패시킨다. 새 환경 변수는 중앙 모듈에서 읽고, 예외는 사유와 함께 대장에 등록한다.
• -오철칙(iron-laws) 점검 워크플로 .github/workflows/iron-laws.yml. 기준선(.iron-laws-baseline.json)에 없던 새 지적만 판정하며 병합을 막지 않는다. 도구는 점검에 쓴 커밋으로 고정했고 범위와 제외 목록은 .iron-laws.yml에 있다.
• -acorn을 개발 의존성으로 명시했다. 환경 변수 접근 점검이 쓴다.

Changed

• -README를 이게 뭔데, 어떻게 돌아가는데, 어떻게 설치하는데, 자주 묻는 질문 순으로 다시 썼다. FAQ는 질문 하나에 답 하나로 나눴고 동작 흐름 다이어그램을 넣었다. 설치 절차는 pgvector 컨테이너와 로컬 임베딩 기준으로 바꿨다.
• -기능 상세, 보안과 운영 점검, 업그레이드 노트, 클라이언트별 연결을 docs/ 아래 문서로 나눴다. 업그레이드 노트는 공통 절차와 상황별 추가 작업으로 다시 썼다. INSTALL.md는 설치 안내 허브로 줄였다.
• -recordSearchEvent의 열 단계별 대체 경로를 함수로 나눠 복잡도를 낮췄다. 동작은 바뀌지 않는다.
• -린트 래칫 기준선을 갱신했다. admin-memory.js의 복잡도와 줄 수가 기록되고, 무처리 catch가 줄어든 oauth.js와 ConflictResolver 값은 낮아졌다.

Fixed

• -OAuth 키 조회가 실패해 키에 묶이지 않은 클라이언트로 격하될 때 아무것도 남지 않던 것을 경고로 남긴다. 권한은 늘지 않는다.
• -인접 링크 격리가 실패해도 기록이 없던 것과 자동 링크의 주제 조회 실패를 경고로 남긴다. 반환값은 그대로다.
• -관리 인증 거부 경고가 console.warn으로 쿼리 문자열까지 기록하고 로거의 민감 정보 마스킹을 우회하던 것을 고쳤다. 경로만 로거로 기록한다.
• -충돌 해소 트랜잭션의 ROLLBACK 실패를 기록한다.
• -건너뛰던 lifecycle 누수 검출 시험을 닫지 않은 net.Server로 확인하는 결정적 시험으로 바꿨다. 타이머는 process._getActiveHandles()에 나타나지 않아 이전 시험은 검출할 수 없었다.

Removed

• -호출처가 없던 logRequest.

Added

• -합성 역질의에 원본 본문 해시를 기록하는 migration-061과 안전한 dry-run 기본 백필 도구를 추가했다. 검색은 현재 본문에서 만든 파생 데이터만 사용하며 긴급 롤백 스위치를 제공한다.
• -임베딩·합성 질의·사례 이벤트와 원본 파편의 amend/forget 경합을 실제 PostgreSQL에서 재현하는 차단 CI 레인을 추가했다.

Changed

• -RRF 후보 병합이 의미·어휘·리랭커 채널의 근거를 보존하고, lexical-only 우선순위를 효용 점수와 분리한다. 컨텍스트 토큰 예산은 공용 토크나이저의 실제 계산값과 진단값을 사용한다.
• -핫 캐시 적중도 본문 해시, 검토 상태, 유효 기간, 키·워크스페이스 범위를 DB와 일괄 대조한다. 승인·거절·수정 직후에는 관련 캐시를 제거한다.
• -기존 데이터 벤치마크는 현재 키·워크스페이스 범위에서 정확한 본문 해시로 기대 파편을 찾고, 누락·중복·비유한 지표·평가 건수 불일치를 실패로 처리한다.

Fixed

• -비동기 임베딩과 합성 역질의가 amend 이전 본문에서 계산된 결과를 최신 파편에 기록할 수 있던 경합을 막았다.
• -파편 삭제와 사례 이벤트 기록이 겹칠 때 출처가 없는 이벤트·증거 파편이 남을 수 있던 경합을 막았다.
• -검색 경로별 중복 후보 병합에서 먼저 계산된 similarity와 lexical 근거가 사라지던 문제를 수정했다.

업그레이드 주의

• -배포 전에 scripts/grant-anchor-permission.js --apply로 앵커를 쓰는 키에 anchor 권한을 준다. 그렇지 않으면 배포 직후 그 키의 앵커 지정이 일반 파편으로 저장된다(MEMENTO_ANCHOR_PERMISSION=warn).
• -migration-053 ~ 060을 적용한다. case_events(source_fragment_id) 색인은 마이그레이션 전에, content_tokens GIN 색인은 마이그레이션 뒤 백필 전에 scripts/ops/online-index.mjs로 만든다. 배포 뒤 backfill-content-tokens.mjs, backfill-key-secrets.mjs --confirm, case_events 백업 뒤 purge-orphan-case-summaries.js를 실행한다. 순서는 docs/operations/online-migration.md의 「migration-053 ~ 060 배포 순서」에 있다.
• -관리자 계정을 등록하기 전에 MEMENTO_ADMIN_SEAL_KEY를 설정한다.

Added

• -관리 콘솔 지식 그래프에 겹치지 않는 토픽별 태양계, 타입별 입체 천체, 공전 애니메이션과 Canvas 노드 드래그를 추가했다. 700개 노드 또는 5,000개 링크 이상은 통제된 원거리 팔레트, LOD, 계 단위 가시 영역 컬링, 6만 링크 예산을 사용하는 고밀도 렌더러로 자동 전환하며 기존 소규모 SVG 그래프는 유지한다.
• -GET /health/live(항상 200)와 GET /health/ready(주 DB가 상한 안에 응답하면 200, 아니면 db_timeout 또는 db_error 사유의 503). GET /health의 응답은 같다.
• -MEMENTO_HEALTH_READY_DB_TIMEOUT_MS(기본 2000): /health/ready의 DB 확인 상한.
• -MEMENTO_SHUTDOWN_DEADLINE_MS(기본 60000, 0은 상한 없음): 종료 절차 전체 상한. 두 번째 종료 신호는 기록만 한다.
• -MEMENTO_AUTH_STORE_UNAVAILABLE_STATUS(401, 503, 기본 401): API 키 저장소 조회 실패로 인증을 판정하지 못한 initialize와 세션 자동 복구의 응답 상태. 503이면 Retry-After: 10을 붙인다.
• -지표 mcp_auth_store_errors_total{operation}. memento_auth_denied_total의 reason에 store_unavailable.
• -MEMENTO_SEMANTIC_THRESHOLD_MODE(inner, outer, 기본 inner): 시맨틱 검색의 유사도 임계값을 이웃 조회 안쪽(현행)에서 적용할지, 바깥에서 적용할지 정한다.
• -MEMENTO_SCORE_UPDATE_BATCH(기본 200, 0은 단일 문장): 감쇠와 utility 점수 갱신을 id 오름차순으로 잠근 묶음 단위로 처리한다. 0이면 단일 문장으로 돌아간다. forget의 linked_to 정리는 이 값과 무관하게 항상 id 오름차순으로 행을 잠근다.
• -MEMENTO_API_KEY_DELETE_GUARD(기본 true): 저장된 파편이나 재통합 이력이 있는 API 키는 삭제하지 않고 409(key_in_use)를 돌려준다. false면 확인을 건너뛴다.
• -npm run test:db: 실제 PostgreSQL에서 행 잠금 순서와 링크 일괄 생성의 정합, 온라인 색인과 재개형 백필, 중복 판정 범위, 작업 기억 행, outbox 작업자, 내보내기와 가져오기 왕복을 확인하는 시험 레인. 실행마다 전용 데이터베이스를 만들고 지운다.
• -node scripts/lint-ratchet.js: 무처리 catch 처리기, 복잡도, 파일 길이, 직접 환경 변수 읽기의 수치가 기준선(scripts/lint-baseline.json)보다 늘면 실패한다. 기준선 상향에는 --update --allow-increase가 필요하다.
• -MEMENTO_CONFIG_STRICT(기본 false): 숫자, 열거, 불리언 환경 변수의 값 문제(숫자 아님, 정수 아님, 허용 범위 밖, 허용 목록 밖)를 기동 시 한 줄로 기록한다. true면 문제가 있을 때 종료 코드 78로 멈춘다. 공백만 있는 값은 미설정과 같다.
• -MEMENTO_SESSION_ID_POLICY(warn, enforce, 기본 warn): MCP 세션 ID 수신 처리. warn은 쿼리스트링 ID와 서버 발급 형식(UUID)이 아닌 ID의 자동 복구를 경고 로그로 기록하고 정상 처리한다. enforce는 쿼리 ID에 400, UUID가 아닌 ID의 복구에 404를 돌려준다. 헤더로 보낸 UUID 세션과 /message?sessionId=는 영향이 없다.
• -MEMENTO_RESERVED_AGENT_IDS(warn, enforce, 기본 warn): 내부 작업 전용 agentId(system, admin) 처리 방식. warn은 API 키 요청의 예약 agentId에 경고 로그(키 앞 8자 포함)만 남기고, enforce는 FORBIDDEN(-32001)으로 거부한다. master 키는 두 방식 모두 허용한다.
• -OAUTH_ACCESS_TOKEN_TTL_SECONDS(양의 정수, 기본 미설정): OAuth 접근 토큰 수명(초). 미설정이면 SESSION_TTL_MINUTES * 60을 쓴다. 리프레시 토큰 수명은 영향받지 않는다.
• -MEMENTO_DCR_MAX_PER_HOUR(기본 100, 0은 상한 없음): /register의 시간당 등록 상한(프로세스 단위). 초과하면 429를 돌려준다.
• -node scripts/purge-oauth-clients.js: 한 번도 쓰이지 않은 오래된 동적 등록 클라이언트를 정리한다. 기본은 미리보기이고 --execute로 삭제한다. --older-than-days(기본 30)를 받으며 키에 묶인 클라이언트는 제외한다.
• -MEMENTO_ADMIN_AUTH_BACKOFF(on, off, 기본 off): on이면 관리 인증이 연속 5회 실패한 뒤 1, 2, 4초 순으로 최대 60초까지 다음 시도를 늦추고, 지연 중에는 올바른 키도 429(Retry-After)를 받는다. 실패 기록은 이 값과 무관하게 남는다.
• -MEMENTO_REMEMBER_DUPLICATE_GUARD(기본 false): true면 remember가 같은 키 범위의 기존 파편과 같은 본문을 받았을 때 기존 파편에 후처리, TTL 조정, 재색인을 하지 않고 응답의 existing, duplicate(same_scope, other_workspace, closed, unknown)로 상태만 알린다.
• -지표 mcp_remember_duplicate_total{kind}: remember 중복 적중을 분류해 센다. 플래그와 무관하게 동작한다.
• -지표 memento_consolidate_split_step_failed_total{step}: 분할 커밋의 rollback_delete, link_related, link_part_of, outcome_record 단계 실패를 센다. 같은 실패는 split <step> failed 경고 로그에도 남는다.
• -npm run release -- X.Y.Z: 작업 트리와 HEAD의 Tests 워크플로 결과를 확인한 뒤 CHANGELOG의 [Unreleased]를 버전 절로 옮기고 package.json, package-lock.json, SKILL.md, SECURITY.md의 버전 표기를 갱신한다. lint와 단위 시험이 통과하면 release: X.Y.Z 커밋과 annotated tag를 만들고 push와 gh release create 명령을 출력한다. main 브랜치에서만 실행되며 다른 브랜치는 --allow-branch가 필요하다.
• -npm run test:coverage와 scripts/check-coverage.js: 단위 시험의 줄, 분기, 함수 커버리지 합계를 coverage-baseline.json(허용 폭 0.5%p)과 비교해 아래로 내려가면 실패한다. 입력이 읽을 수 없거나 기준선이 객체가 아니면 종료 코드 2로 끝난다. --write는 기준선을 낮추지 않으며 낮추는 갱신은 --allow-decrease가 필요하다. CI의 단위 시험 단계가 이 명령을 쓴다.
• -관리 /stats의 healthFlags에 trust_proxy_hops_unset. TRUST_PROXY_HOPS가 미설정인 상태에서 X-Forwarded-For를 처음 받으면 [Proxy] 경고를 프로세스당 한 번 남긴다. 기동 시 운영 권장 설정 중 빠진 이름은 [Startup] Recommended settings not applied: 한 줄로 나열한다.
• -도구 호출 감사 기록에 행위자 정보(key=, sid= 앞 8자, ip=)가 붙는다. 관리 API의 변경 요청(GET 제외)과 관리 인증의 성공과 실패가 admin_auth, admin <METHOD> <path> 감사 기록으로 남는다.
• -remember, amend, link, tool_feedback의 열거형 인자 값이 저장소 제약에 맞지 않으면 Invalid arguments for <tool>: <param>: must be one of a|b|c 메시지와 code: "INVALID_ARGUMENT"를 돌려준다.
• -기동 점검 실패는 [Startup] 오류 로그로, 리랭커 사전 적재 실패는 [Reranker] preload failed (non-fatal) 경고로 남는다.
• -MEMENTO_DECAY_MIN_DELTA(기본 0): 묶음 갱신에서 감쇠량이 이 값보다 작은 행을 건너뛴다. 마지막 감쇠 후 24시간이 지난 행은 항상 갱신한다. 숫자가 아니거나 음수인 값은 0으로 처리하고 경고를 남기며 1을 넘는 값은 1로 제한한다. MEMENTO_SCORE_UPDATE_BATCH가 0이면 적용하지 않는다.
• -MEMENTO_UTILITY_MIN_DELTA(기본 0): 묶음 갱신에서 저장된 utility_score와의 차이가 이 값 이하인 행을 다시 쓰지 않는다. 값 처리와 적용 조건은 MEMENTO_DECAY_MIN_DELTA와 같다.
• -node scripts/import-cycles.js: lib, config, scripts, bin, server.js의 상대 경로 import에서 크기 2 이상의 순환을 찾아 정적 import만 본 결과와 동적 import를 포함한 결과를 따로 출력한다. 단위 시험은 정적·동적 포함 순환 모두 0건인지 확인한다.
• -docs/operations/monitoring.md: 공유 Prometheus 인스턴스용 스크레이프 잡과 경보 규칙. 문서의 규칙이 참조하는 지표 이름과 라벨은 단위 시험이 등록된 지표와 대조한다.
• -지표 mcp_session_rotation_total{outcome}(rotated, not_found, expired, forbidden, unavailable, error)와 mcp_rotate_rate_limited_total: 세션 회전 요청의 결과와 rate limit 거부를 센다.
• -지표 mcp_sse_rate_limited_total: IP 한도로 거부된 GET /sse 요청 수를 센다. 거부는 주소를 담지 않는 [SSE] connection request rejected by IP rate limit 경고 로그로도 남는다.
• -MEMENTO_LLM_CLI_TOOL_APPROVAL(none, all, 기본 none): gemini-cli, copilot-cli, opencode-cli의 도구 실행 승인 방식. 기본에서 세 CLI는 제한된 승인으로 실행된다. gemini는 -y 없이, copilot은 쓰기, 셸, URL 도구와 내장 MCP를 거부하는 인자와 함께, opencode는 OPENCODE_PERMISSION={"*":"deny"}로 실행되며, 세 CLI 모두 서버 작업 디렉터리가 아닌 빈 임시 디렉터리에서 시작한다. all이면 gemini -y, copilot --allow-all-tools를 쓰고 서버 작업 디렉터리에서 실행하며 opencode에는 승인 관련 설정을 더하지 않는다.
• -벤치마크 isolated 모드는 격리 키 benchmark-harness-key(상태 inactive) 행을 api_keys에 한 번 만든다. --save-baseline은 임베딩 provider, 모델, 차원을 기준선 파일에 함께 기록하고, --baseline 비교는 모델이나 차원이 다르면 경고한다.
• -마이그레이션 lint 규칙(번호 050 이상 파일, npm run lint:migrations): no-concurrently(CONCURRENTLY 금지), large-index-unregistered, large-index-table-mismatch, large-index-if-not-exists. 대형 표(fragments, fragment_links, case_events, search_events)의 CREATE INDEX는 이름이 있고 IF NOT EXISTS를 가지며 scripts/ops/index-manifest.json에 등록된 색인이어야 한다. DO 블록 같은 달러 인용 본문과 EXECUTE 문자열도 코드로 검사한다.
• -node scripts/ops/online-index.mjs: 작업 목록의 대형 표 색인을 쓰기를 막지 않고 만든다. 접속 대상은 --url 또는 PG 환경변수로만 받고 .env를 읽지 않는다. --dry-run은 연결 없이 단계를 출력하고, 실행에는 --confirm과 디스크 여유 입력(--data-dir 또는 --free-bytes)이 필요하다. 표 크기의 2배 미만이면 거부하고, 무효 색인은 정리한 뒤 lock_timeout과 교착에 한해 대기를 늘리며 다시 시도한다.
• -lib/memory/consolidate/resumableBackfill.js의 runResumableBackfill: id 오름차순 묶음 갱신으로 대형 표를 채우는 재개형 도우미. 묶음마다 watermark(agent_memory.backfill_watermarks)를 기록해 같은 작업 이름으로 다시 실행하면 이어지고, 행 단위 오류(SQLSTATE 22, 23 계열)는 그 행을 agent_memory.backfill_failures에 기록하고 건너뛴다. 절차는 docs/operations/online-migration.md에 있다.
• -scripts/ops/backup.sh: agent_memory 스키마의 pg_dump -Fc 덤프, 체크섬, 표별 행 수 매니페스트, 역할 정의 덤프를 한 벌로 만든다. 기본 보관은 최근 14일(--keep, MEMENTO_BACKUP_KEEP_DAYS), 저장 위치는 --dir 또는 MEMENTO_BACKUP_DIR이다. --label NAME 벌은 보관 정리에서 제외되고 --prune-labelled로만 지운다. --dry-run은 접속하지 않는다. 저장 위치의 권한과 링크를 검사하고 파일은 600으로 만든다.
• -scripts/ops/restore-verify.mjs: 덤프를 일회용 시험 서버(포트 35433 또는 DB_LANE_SERVER_ALLOW로 명시한 한 곳)의 임시 데이터베이스에 복원하고, 체크섬, 표별 행 수, 마이그레이션 이력, HNSW 색인 유효성을 매니페스트와 대조해 JSON으로 보고한다. 그 밖의 대상에는 연결하기 전에 거부한다. docs/operations/backup-restore.md에 일일 백업, 복구 훈련, 단일 파편 복구, 마이그레이션 전 백업(--label pre-migration) 절차가 있다.
• -node scripts/measure/recall-metrics.mjs: 평가 세트(tests/fixtures/recall-eval-v2)의 질의를 일회용 시험 서버의 데이터베이스에 실행해 R@1, R@5, R@10, MRR, 토큰 예산 내 nDCG, hard negative 선행 비율, 지연(cold, warm 동시성 1과 8)을 부분집합과 태그, 영역별로 JSON으로 낸다. 합격 판정은 하지 않는다. --compare 기준.json 후보.json은 질의별 짝지은 부트스트랩 95% 구간(시드 지정, 표본 수 미달 묶음 표시)으로 두 실행을 비교한다. 평가 세트 형식과 질의 추가 절차는 tests/fixtures/recall-eval-v2/README.md에 있고, 실제 질의와 라벨은 git이 무시하는 tests/fixtures/recall-eval-v2/private/에 둔다.
• -모든 도구가 title과 네 가지 annotations(readOnlyHint, destructiveHint, idempotentHint, openWorldHint)를 boolean으로 선언한다. destructiveHint는 forget, amend, memory_consolidate, apply_update가 true다. 도구별 값과 기준은 docs/api-reference.md의 도구 힌트 표에 있다.
• -ping 메서드: 인증된 세션에서 빈 객체 {}를 돌려주고, 알림으로 보내면 응답 없이 수락한다.
• -PATCH /v1/internal/model/nothing/keys/:id/policy: API 키의 default_mode(recall-only, write-only, onboarding, null), allowed_workspaces(문자열 배열 또는 null, 최대 64개, 항목당 길이 제한), symbolic_hard_gate(boolean)를 전달한 필드만 한 문장으로 갱신한다. 알 수 없는 필드, 빈 객체, 마스터 전용 preset(audit)은 400이다. 변경은 admin key_policy 감사 기록(필드 이름과 이전, 이후 값)으로 남고 조회 캐시를 비운다. 관리 콘솔의 키 상세에 ACCESS POLICY 카드가 있고, 키 목록 응답은 세 정책 열을 포함한다.
• -config/switches.js의 스위치 대장: 기능 스위치 80개의 이름, 기본값, 용도, 분류를 한곳에 두고 환경에서 실제로 적용되는 값을 사용처와 같은 규칙으로 계산한다. npm run switches는 적용 값, 기본값, 상태, 기본과 다름, 분류를 표로 출력하고(.env 파일은 읽지 않는다), --strict는 값이 잘못된 스위치가 있으면 종료 코드 1로 끝난다.
• -관리 /stats 응답의 switches(total, on, off, mode, nonDefaultCount, nonDefault, invalid)와 기동 로그의 [Startup] switches: total=N on=N off=N mode=N nonDefault=N ... invalid=N 한 줄. 값은 담지 않는다.
• -의미 쓰기 관문(WriteGate): remember, amend, batch_remember, reflect 파생 쓰기, AutoReflect, 관리 가져오기, CLI 가져오기, CLI remember 로컬 모드, 통합 분할 자식이 같은 관문(정규화, 민감 정보 마스킹, 유형별 길이 상한, PolicyRules, workspace 허가, 앵커 권한)을 트랜잭션 밖에서 거친다. 위반은 validation_warnings로 알리고 api_keys.symbolic_hard_gate=true 키에서만 거부한다. 판정은 지표 memento_write_gate_total{entry,outcome}(pass, warn, reject)로 센다.
• -MEMENTO_WRITE_GATE(on, off, 기본 on): off이면 진입점별 기본 단계만 적용한다. 호출 시점에 읽는다.
• -MEMENTO_LOG_STDERR(기본 false): true이면 콘솔 로그를 모든 수준에서 표준 오류로 보낸다. CLI는 serve를 뺀 명령에서 값이 없으면 true로 정해 --json 출력을 포함한 표준 출력을 명령 결과에만 쓴다.
• -FragmentWriter의 의미 메서드(insert, update)는 관문을 거치지 않은 의미 열(content, topic, keywords, is_anchor, workspace, key_id, context_summary, goal, outcome) 쓰기를 실행 시점에 거부한다. 의미 열을 쓰는 SQL이 FragmentWriter와 허용 목록 밖에 없는지 tests/structure의 구조 검사가 단위 시험(npm test, npm run test:coverage)에서 확인한다.
• -MEMENTO_SENSITIVE_SCAN(mask, reject, off, 기본 mask)과 민감 정보 규칙 표: 쓰기 관문이 content, topic, contextSummary, goal, outcome과 keywords(소문자로 바꾸기 전 값)에서 API 키와 토큰(sk-, GitHub, AWS, Slack, JWT, Bearer, mmcp_), PEM 개인 키, 주민등록번호, 카드 번호, 이메일, 비밀번호 필드, 휴대전화 번호를 표식으로 바꿔 저장한다. 이메일과 휴대전화 번호를 뺀 탐지는 validation_warnings에 sensitive.<규칙> 이름만 남기며 일치한 문자열은 기록하지 않는다. api_keys.symbolic_hard_gate=true 키는 고신뢰 탐지에서 -32003으로 거부하고, reject이면 마스터 키를 포함한 모든 키가 거부한다. off(또는 MEMENTO_WRITE_GATE=off)이면 레거시 규칙(API 키, 이메일, 비밀번호 필드, 휴대전화 번호)만 content에 적용한다. 로그 마스킹도 같은 규칙 표를 쓴다.
• -MEMENTO_DEDUP_SCOPE(workspace, key, 기본 workspace)와 migration-050(키와 workspace 단위 content_hash 유일 색인 uq_frag_hash_ws_per_key, uq_frag_hash_ws_master): 같은 키가 다른 workspace에 같은 본문을 쓰면 별도 파편으로 저장하고, 같은 workspace나 전역 파편에 같은 본문이 있으면 그 id를 돌려준다. 판정은 실행 시점의 유효 색인을 따르며 키 단위 색인(uq_frag_hash_per_key, uq_frag_hash_master)이 남아 있는 동안은 키 단위로 동작한다. 운영 DB는 scripts/ops/online-index.mjs로 새 색인을 만든 뒤 node scripts/ops/finish-dedup-scope.mjs --confirm으로 키 단위 색인을 지워 전환을 마친다(절차와 되돌리기는 docs/operations/online-migration.md). remember가 같은 범위의 기존 파편에 적중하면 응답의 duplicate_of에 그 id를 싣는다.
• -MEMENTO_WM_PG_FALLBACK(on, off, 기본 on)과 MEMENTO_WM_FALLBACK_MAX_ROWS(기본 2000): Redis가 준비되지 않았을 때 remember(scope=session)를 fragments의 작업 기억 행(source=wm-fallback)으로 받고, context의 WORKING 구획, 세션 종합(reflect), 소비 항목 제거가 같은 행을 읽는다. 행은 recall, 통합, 할당량, 관리 화면과 CLI stats 집계, 내보내기에 나타나지 않으며 24시간 뒤 정리된다. 키별 행 수가 상한에 닿으면 오래된 행부터 지운다. 응답의 working_memory(redis, postgres-fallback, none)와 _meta.hints가 저장 경로를 알린다.
• -MEMENTO_RANK_BEFORE_BUDGET(on, off, 기본 on)과 migration-051(search_events.candidate_count, budget_kept): recall이 토큰 예산으로 자르지 않은 후보(최대 200건)에 연결 파편을 합쳐 최종 점수를 매긴 뒤 tokenBudget 안에서 고른다. 후보 전체가 예산 안이면 off와 같은 집합을 고른다. off이면 검색 순서대로 예산을 자른 뒤 연결 파편을 합친다. 두 열이 없는 DB에서는 검색 이벤트를 열 없이 기록하고 5분마다 다시 확인한다.
• -recall-metrics --compare --metric <지표>: 지정한 지표만 짝지은 부트스트랩으로 비교한다. 측정 실행은 --include-links를 받고 결과에 include_links, rank_before_budget을 기록한다.
• -트랜잭션 outbox(migration-052의 outbox_events, lib/outbox): 변경 트랜잭션 안에서 이벤트를 기록하고, 작업자가 SKIP LOCKED 점유와 임대로 topic별 처리기에 전달하며 재시도(MEMENTO_OUTBOX_MAX_ATTEMPTS, 기본 12), dead-letter, 보존 정리(MEMENTO_OUTBOX_RETENTION_DAYS, 기본 7)를 한다. 처리기가 없는 topic의 미점유 행은 MEMENTO_OUTBOX_UNHANDLED_DAYS(기본 7) 뒤 dead-letter로 옮긴다. 스위치는 MEMENTO_OUTBOX(기록과 작업자 전체)와 MEMENTO_OUTBOX_WORKER(이 프로세스의 작업자)이며 둘 다 기본 on이다. 지표 memento_outbox_*와 경보 MementoOutboxLag, MementoOutboxDeadLetter, MementoOutboxStatsStale이 docs/operations/monitoring.md에 있다. 처리기가 있는 topic은 audit.record, audit.llm.egress, hook.reflect다(각 항목 참조).
• -내보내기 형식 버전 2: GET /export와 CLI export가 머리 줄, 파편의 전체 열, 링크 줄, 선택적 수정 이력 줄(include_versions, CLI --include-versions), 끝 줄을 낸다. format_version=1(CLI --format-version 1)은 버전 1 형식을 낸다. 형식 버전과 호환 규칙은 docs/api-versioning.md에 있다.
• -가져오기 실행기: POST /import와 CLI import가 버전 1과 2 파일을 읽어 파편, 링크, 수정 이력을 기록하고 imported, duplicates, rejected(rejected_by_reason), errors, transformed, ignored 집계를 돌려준다. 기록 대상 키는 key_id(CLI --key)가 정하며 파일 행의 key_id는 읽지 않는다. restore=trusted(CLI --restore)는 버전 2 파일의 저장 값(importance, ttl_tier, workspace_source, 품질 판정 열)을 되살리고 감사 기록을 남긴다. 알아볼 수 있는 기록이 없는 입력은 400 no_valid_records(CLI 종료 코드 1)다.
• -MEMENTO_DB_LOCK_RETRY_MAX(0 이상 10 이하, 기본 3, 0은 재시도 없음): 여러 파편 행을 잠그는 쓰기 트랜잭션이 교착(40P01)이나 잠금 대기 상한(55P03)으로 끝나면 처음부터 다시 실행한다. 지표 memento_db_deadlock_retries_total{operation}과 경보 MementoDbLockRetries, 경고 로그로 끝낸 배경 쓰기 실패를 세는 memento_db_write_failures_total{operation}.
• -본문 어휘 채널 MEMENTO_LEXICAL_CHANNEL(on, off, 기본 on)과 migration-053(fragments.content_tokens): 본문을 쓰는 저장 경로가 본문의 형태소 토큰을 같은 문장으로 기록하고, recall의 text 검색이 유효한 GIN 색인(idx_fragments_content_tokens, 정의로 찾는다)이 있을 때 전문 검색 후보를 RRF에 더한다. 임베딩이 꺼진 경로에서도 text만으로 찾는다. 어휘 채널에서만 찾은 후보는 다른 채널 후보 뒤에서 순위와 토큰 예산을 받는다. 질의 상한 MEMENTO_LEXICAL_TIMEOUT_MS(기본 120), 기존 행 백필 scripts/backfill-content-tokens.mjs(기본 미리보기, --confirm), 지표 memento_lexical_tokens_coverage_ratio, memento_lexical_tokens_missing, memento_lexical_channel_skipped_total{reason}, memento_lexical_tokenize_skipped_total{reason}.
• -MEMENTO_CONTEXT_ANNOTATE(on, off, 기본 on): context 주입 줄 끝에 저장일(UTC)과 assertion 주석 (YYYY-MM-DD, assertion)을 붙인다. 주석의 고정 비용은 토큰 예산 선택에 들어간다. recall의 format:"pack"은 답 꾸러미(pack.text, items, groups, policy)를 돌려준다. 출처와 대체 체인 조회가 실패하면 partial=true다.
• -파편 출처와 신뢰 등급 MEMENTO_PROVENANCE(on, off, 기본 on)와 migration-057(origin, observed_client, trust_tier, review_state, review_reason): remember와 batch_remember의 origin 주장(user_stated, agent_inferred, tool_output, external_content, consolidation, import, 그 밖의 값은 -32602), 관측 클라이언트 이름, 키 상한(권한 표지 trusted_origin 또는 마스터 키 3, 그 밖 2)으로 등급을 정한다. 등급 1 이하 파편은 ANCHOR와 CORE 주입에서 빠지고, recall 응답과 답 꾸러미, 주입 줄 주석에 출처가 실린다. 지표 memento_context_core_trust_excluded_total{reason}.
• -비차단 검토 대기열 MEMENTO_REVIEW_QUEUE(on, off, 기본 on)와 migration-058(memory_review_decisions): 에이전트 지시 덮어쓰기 문구, 등급 1 이하의 앵커와 preference와 procedure, 무권한 앵커 요청에 걸린 쓰기를 거부하지 않고 검토 대기로 저장한다. 검토 대기 파편은 쓴 키의 recall에만 pending_review 표지와 함께 보이고 주입과 앵커 승격에서 빠진다. 키 권한 목록의 review_off, review_all 표지가 키별 방식을 정한다. 관리 API GET /review, POST /review/:id/approve, POST /review/:id/reject(능력 review.decide, 감사 행위 review.approve, review.reject)와 30일 미결정 자동 거절(review.auto_reject). 보류한 앵커는 승인 때 쓰기 경로와 같은 앵커 권한과 키별 상한으로 판정한다. 지표 memento_review_flag_total{entry,reason}, memento_review_decisions_total{decision}.
• -MEMENTO_FORGET_CASCADE(on, off, 기본 on)와 migration-054(case_events(source_fragment_id) 부분 색인, 운영 DB는 online-index로 먼저 만든다): forget이 대상과 그 대상을 가리키는 모순 해소 기록을 함께 지우고 지운 파편을 출처로 한 사례 요약을 [삭제됨]으로 바꾼다. 응답 purged(case_summaries, audit_fragments). 모순 해소 기록은 두 파편의 id만 담는다. 남은 고아 요약 정리 scripts/purge-orphan-case-summaries.js(기본 미리보기, --execute는 --i-have-a-backup과 함께).
• -LLM 외부 전송 정책 MEMENTO_EGRESS_POLICY(on, off, 기본 on), MEMENTO_EGRESS_UNKNOWN_KEY(configured, local_only, 기본 configured), MEMENTO_EGRESS_LOCAL_HOSTS와 migration-055(api_keys.egress_policy): 외부 LLM 호출 전에 키와 workspace 정책으로 제공자를 거르고 본문을 마스킹하며 전송을 outbox topic audit.llm.egress로 감사한다(파일 감사 로그와 감사 표에 함께 남는다). 키 정책 편집(PATCH /keys/:id/policy)의 egress_policy 필드는 능력 egress.policy가 필요하다. 지표 memento_llm_egress_*.
• -감사 표 MEMENTO_AUDIT_DB(on, off, 기본 on), MEMENTO_AUDIT_RETENTION_DAYS(기본 400)와 migration-056(admin_audit_events): 관리 변경, 관리 인증, 기억 쓰기, 앵커, 관문 거부, 검토 결정, 외부 전송을 해시 체인으로 기록한다. 관리 API GET /audit, GET /audit/export(JSONL), POST /audit/verify와 CLI anchormind audit verify.
• -관리 권한 결정 표: 관리 API의 라우트마다 요구 능력과 범위를 선언한 라우트 표(lib/admin/admin-route-table.js)로 판정한다. 역할 프리셋 owner, admin, reviewer, auditor, viewer, service, 표에 없는 경로는 owner 전용, 관리 SQL의 workspace 범위 술어, auditor 응답 마스킹, GET /me, GET /me/explain(API 키 Bearer 포함).
• -API 키 수명과 migration-059(api_keys 수명 열, api_key_secrets): 만료 시각, 허용 주소 대역, 소유자, 종류, 설명을 두고 POST /keys/:id/rotate(겹침 MEMENTO_KEY_ROTATION_GRACE_HOURS, 기본 24), POST /keys/:id/revoke, POST /keys/:id/access-review, PATCH /keys/:id로 관리한다. 마지막 사용 기록 간격 MEMENTO_KEY_LAST_USED_INTERVAL_SEC(기본 60). 배포 뒤 scripts/ops/backfill-key-secrets.mjs --confirm으로 현재 키 해시를 옮긴다.
• -관리자 계정 MEMENTO_ADMIN_USERS(on, off, 기본 on), MEMENTO_ADMIN_SEAL_KEY와 migration-060: 비밀번호와 TOTP(또는 복구 코드) 로그인, DB 세션 쿠키(SameSite=Strict)와 이중 제출 CSRF, 역할 바인딩, 계정 관리 API(/admin-users, 능력 admin_user.manage, owner 전용), 첫 owner 등록(POST /admin-users/bootstrap, 마스터 키), 비상 복구 CLI anchormind admin recover(명시한 접속 대상만 쓰고 환경 파일을 읽지 않는다).
• -앵커 권한 MEMENTO_ANCHOR_PERMISSION(off, warn, enforce, 기본 warn)과 MEMENTO_ANCHOR_LIMIT_PER_KEY(기본 1000): remember, batch_remember, amend의 앵커 지정은 마스터 키와 권한 목록에 anchor가 있는 키만 하고 키별 살아 있는 앵커 수 상한을 쓰기 트랜잭션 안에서 다시 센다. warn은 일반 파편으로 저장하고 anchorPermissionRequired, anchorLimitExceeded 경고와 지표 memento_anchor_decision_total{outcome,reason}을 남기며, enforce는 거부한다. 최근 90일 앵커를 만든 키에 권한을 주는 scripts/grant-anchor-permission.js(기본 미리보기, --apply).
• -읽기 경로 workspace 허가 MEMENTO_WORKSPACE_READ_AUTHZ(off, warn, enforce, 기본 warn): recall, context, graph_explore, fragment_history, reconstruct_history, search_traces, resources/read의 대상 workspace를 키의 allowed_workspaces로 판정한다. warn은 지표 memento_workspace_read_authz_total과 로그만 남기고 enforce는 -32001로 거부한다. master 전용 mode preset 요청도 같은 스위치로 판정한다.
• -하네스 훅 MEMENTO_HOOK_ENDPOINTS(on, off, 기본 on): POST /hooks/{client}/{event}(Claude Code, Codex의 SessionStart, Stop, SessionEnd)가 세션 시작 맥락을 돌려주고 세션 끝 발췌의 요약 후보를 outbox로 회고에 넘긴다. CLI anchormind hook(현재 디렉터리의 .env를 읽지 않는다)과 플러그인 생성 anchormind init --target claude|codex(기본 dry-run, --write). 지표 memento_hook_calls_total.
• -만료 GC 처리량 MEMENTO_GC_THROUGHPUT(on, off, 기본 on), MEMENTO_GC_MAX_DELETE_PER_CYCLE(기본 4000), MEMENTO_GC_TIME_BUDGET_MS(기본 60000): 만료 파편 정리가 100건 청크를 주기당 상한과 시간 예산까지 반복한다. 지표 memento_gc_backlog.
• -지표 memento_modern_protocol_attempts_total: 세션 없이 들어온 현대식 MCP 프로토콜 시도를 센다.
• -관리 콘솔: 키 상세의 LIFECYCLE 카드(만료, 소유자, 종류, 허용 주소, 회전, 폐기, 접근 검토 서명), 감사 로그 화면(조건 조회, 이어 보기, JSONL 내보내기, 체인 검증), 관리자 계정 화면(계정 목록, 생성, 역할 교체, 비활성화, TOTP 초기화, 세션 폐기, 첫 owner 부트스트랩), 로그인 화면의 관리자 계정 경로(비밀번호, TOTP 또는 복구 코드, TOTP 등록)가 있다. 사용법은 docs/admin-console-guide.md에 있다.
• -측정 스크립트: scripts/measure/context-annotation-tokens.mjs(context 주입 줄 주석과 답 꾸러미의 토큰 증가를 DB 없이 측정), scripts/measure-hook-latency.mjs(훅 회고 접수 지연을 일회용 시험 서버에서 측정), scripts/measure/protocol-era-probe.mjs(현대식 MCP 요청의 era 판정과 initialize 폴백 관찰).

Changed

• -LLM CLI 실행 구현을 lib/llm/runners/로 분리하고 provider는 raw runner만 참조하도록 정리했다. 기존 lib/agy.js, lib/codex.js, lib/copilot.js, lib/gemini.js, lib/opencode.js, lib/qwen.js 공개 경로와 export는 호환 shim으로 유지한다.
• -모순 해소 감사 기록은 MemoryManager 역참조 대신 생성자에 주입한 rememberAudit 콜백을 사용한다. 감사 기록 실패가 모순 해소를 되돌리지 않는 계약은 유지된다.
• -관리자 모듈 디스패치를 admin-handler-registry.js로 분리했다. 라우트 표와 레지스트리 모듈 집합의 누락·추가·중복을 기동 시 거부하고 admin-audit를 admin-export보다 먼저 실행한다.
• -import 순환 허용 목록을 비웠다. 정적 순환과 동적 import 포함 순환은 모두 0건이어야 한다.

• -API 키로 연 MCP 세션은 사용할 때 키 상태를 MEMENTO_SESSION_KEY_RECHECK_MS(기본 30000ms, 0이면 끔) 주기로 다시 읽는다. 비활성 또는 삭제된 키의 세션은 닫히고 404 Session not found를 받으며, 권한 변경은 열린 세션에 반영된다. 관리 API로 키를 비활성화하거나 삭제하면 이 프로세스의 그 키 세션이 즉시 닫힌다.
• -전이 의존성 moment를 2.31.0으로 올렸다(package-lock.json).
• -initialize의 협상 프로토콜 버전은 항상 지원 목록(2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) 중 하나다. YYYY-MM-DD 형식이 아닌 값은 가장 오래된 지원 버전으로, 목록 사이의 날짜는 그 이하의 가장 가까운 지원 버전으로 협상한다. mcp_protocol_version_negotiations_total의 requested_version, negotiated_version과 mcp_protocol_version_reanchored_total의 from, to 라벨 값은 지원 버전, none, other(from은 null 포함)다.
• -README와 벤치마크 문서의 LongMemEval 수치에 측정 조건(데이터셋, 단계별 소요 시간)과 논문 링크(arXiv 2410.10813)를 맞춘다. 임베딩 없이 동작하는 회상 범위를 명시한다.
• -키에 묶인 OAuth 클라이언트의 토큰 교환은 해당 키를 client_secret(또는 Basic 인증)으로 제시한 요청에서만 성립한다. API 키 원문 형식의 client_id는 클라이언트 행으로 등록하지 않는다.
• -키에 묶인 OAuth 클라이언트의 인가 요청은 redirect_uri가 허용 목록에 있어도 항상 동의 화면을 거친다.
• -POST /token은 invalid_client 오류에 HTTP 401을 돌려준다. 오류 코드는 표준 invalid_client다. 다른 오류는 400이다.
• -키에 묶여 등록된 클라이언트의 동적 등록 응답은 token_endpoint_auth_method로 client_secret_post를 알린다. 묶이지 않은 등록은 none이다.
• -initialize 안내문의 recall 호출 예시는 인자 이름으로 text를 쓴다.
• -remember의 keywords는 유한한 숫자를 받아 문자열로 바꿔 저장한다. 문자열과 숫자가 아닌 항목은 코드 -32602 검증 오류로 거절한다.
• -tool_feedback의 링크 재통합은 양 끝 파편이 모두 호출 키 범위에 있는 링크에만 적용된다.
• -도구 응답의 오류 문구는 내부 예외 원문 대신 공용 메시지를 쓴다. 원문은 로그와 감사 기록에만 남는다.
• -remember의 supersedes는 호출한 키가 소유한 유효 파편에만 적용된다. 다른 키의 파편이나 이미 닫힌 파편은 링크 없이 경고 로그만 남긴다.
• -utility 점수와 중요도 하향 갱신은 저장값이 실제로 바뀌는 행만 기록한다.
• -의존성 감사(audit:ci)는 별도 워크플로(audit.yml)에서 push, pull request, 매일 예약 실행으로 돈다. 단위 시험은 감사 결과와 무관하게 실행된다.
• -도구 인자 점검이 스키마의 maxLength, maxItems, pattern, oneOf를 해석한다. amend의 본문은 remember와 같은 길이 상한을 따른다. 점검 모드의 기본값은 warn이다.
• -와치독 스크립트(memento-watchdog.sh)는 /health/live가 응답하지 않을 때만 서비스를 재시작하고, 연속 재시작의 간격을 지수로 늘리며, 중복 실행을 잠금으로 막는다. 상태는 재시작 전에 기록한다.
• -종료 신호를 받은 서버는 MEMENTO_SHUTDOWN_DEADLINE_MS 안에 종료하지 못하면 종료 코드 1로 강제 종료한다.
• -실제 PostgreSQL에서 행 잠금 순서와 링크 일괄 생성의 linked_to 정합을 확인하는 npm run test:db와 CI 작업 DB Concurrency (with DB)를 추가한다. 이 작업은 결과를 보고만 한다.
• -로그와 reflect 프롬프트에 나오는 세션 ID는 앞 8자만 표기한다. 접근 로그와 Redis 세션 로그도 같다. 클라이언트에 보내는 endpoint 이벤트의 ID는 전체 값이다.
• -숫자, 열거, 불리언 환경 변수는 공용 도우미로 읽는다. 숫자가 아닌 값은 기본값으로 돌아가고, 정수가 아니거나 허용 범위 밖인 값은 그대로 쓰며 기록만 한다. MEMENTO_HEALTH_READY_DB_TIMEOUT_MS(100 이상 4500 이하), MEMENTO_SHUTDOWN_DEADLINE_MS(0 이상), MEMENTO_SCORE_UPDATE_BATCH(0 이상, 10000 초과는 10000), MEMENTO_SESSION_KEY_RECHECK_MS(0 이상)는 범위 밖이면 기본값을 쓴다. 비어 있는 LLM_CB_* 값은 기본값이다.
• -OAuth 토큰 수명은 접근 토큰 OAUTH_ACCESS_TOKEN_TTL_SECONDS(미설정이면 세션 수명), 리프레시 토큰 OAUTH_REFRESH_TTL_SECONDS(SESSION_TTL_MINUTES * 60 * 2, 기본 60일)로 각각 정해진다. 인가 코드 교환으로 발급되는 리프레시 토큰의 만료도 OAUTH_REFRESH_TTL_SECONDS를 따른다.
• -도구 설명에서 내부 이력 표기와 단계 번호 문구를 줄였다. tools/list 응답은 일반 키 기준 약 1.1KB 작다. context의 types 기본값 문구는 실제 기본값과 같은 목록에서 만든다.
• -도구 감사 기록의 ip=는 resolveClientIp가 채택한 클라이언트 주소다. 관리 감사 기록의 경로 표기는 세션과 키의 UUID 구간을 앞 8자로 줄인다.
• -SECURITY.md의 지원 버전 표는 5.12.x까지를 지원으로 적는다.
• -npm run test:db는 감쇠와 utility 묶음 갱신의 잠금 순서, 무변경 재기록, 최소 변화량 시험도 실행한다. 표 전체를 갱신하는 시험은 이 직렬 레인에만 둔다.
• -GET /sse(레거시 SSE 연결)는 클라이언트 IP별 요청 제한을 받는다. 한도(RATE_LIMIT_PER_IP, 기본 분당 30)는 /token, /register, /authorize, initialize의 IP 한도와 같은 버킷을 쓰며, 초과하면 429와 Retry-After(창 길이 초)를 돌려준다.
• -관리 콘솔은 Tailwind CSS 3.4.17과 d3 7.9.0 스크립트를 assets/admin/vendor/에서 제공한다. 콘솔 응답의 CSP 헤더는 script-src 'self' 'unsafe-inline'이며 외부 스크립트 호스트를 허용하지 않는다. 사본의 출처와 sha256은 assets/admin/vendor/PROVENANCE.md에 있다.
• -벤치마크 CLI는 적재 전에 대상 DB(host, port, database)를 한 줄로 출력한다. 임베딩된 파편이 0건인 실행(--no-seed 포함)은 --save-baseline을 거부한다. 기준선 갱신 절차와 측정 조건은 docs/benchmark.md에 있다.
• -모듈 사이에 정적 import 순환이 없다. 공용 부분은 lib/safe-compare.js, lib/memory/write/affect.js, lib/embeddings/normalize.js가 가진다.
• -설정 문서(docs/configuration.md, docs/configuration.en.md)와 .env.example에 숫자, 열거, 불리언 환경 변수의 허용 범위와 와치독 환경 변수(MEMENTO_WATCHDOG_*)를 싣는다.
• -/register의 시간당 상한은 유효한 API 키를 Bearer로 제시한 등록과 그 밖의 등록을 같은 값으로 따로 센다. 429의 Retry-After는 현재 창이 끝나기까지 남은 초(올림, 최소 1, 최대 3600)다.
• -클라이언트 IP로 채택한 X-Forwarded-For 항목이 IPv4 또는 IPv6 주소 표기가 아니거나 45자를 넘으면 소켓 주소를 쓴다. 이 경우 값을 담지 않은 [Proxy] forwarded address entry is not a valid IP address 경고를 프로세스당 한 번 남긴다.
• -도구 인자 점검 경고는 [ToolArgs] <도구>: <오류> (key=<키 ID 또는 master 또는 none> sid=<세션 ID 앞 8자> ua=<User-Agent>) 형식으로 호출자를 표기한다. User-Agent는 제어 문자와 키 형태 토큰을 제거하고 64자로 줄이며, 값이 없으면 unknown이다.
• -기동 시 설정 점검(MEMENTO_CONFIG_STRICT)이 호출 시점에 읽는 스위치도 본다. 대상은 도구 인자 점검, 세션 ID 처리, 예약 agentId, 관리 인증 지연, 키 삭제와 중복 저장 보호, OAuth 리디렉션 점검, CORS, 프레임 옵션, SSE 쿼리 키, CLI 도구 승인 같은 열거형과 true, false 스위치(Redis, 캐시, 재통합, 리랭커, 인증 비활성화, OpenAPI, 동적 등록 계열 포함)다. 허용되지 않은 값은 기동 점검 목록에 올라가며 실제 적용되는 값은 달라지지 않는다.
• -파라미터를 선언하지 않은 도구는 저장소 제약 위반에도 파라미터 이름을 말하지 않고 Internal error를 돌려주며 code를 붙이지 않는다. batch_remember의 항목 type 제약은 Invalid arguments for batch_remember: type: must be one of ... 형식으로 안내한다.
• -세션 회전 요청은 mcp_session_rotation_total을 요청당 한 번만 센다. 성공 응답 전송이 실패해도 rotated 외의 결과를 더하지 않는다.
• -node scripts/import-cycles.js의 허용 목록은 항목마다 사유를 가지며, 더 이상 순환이 아닌 항목은 시험이 실패시킨다. 존재하지 않는 파일을 가리키는 상대 경로 import는 unresolved relative imports로 출력되고, 검사 범위에 scripts와 bin이 들어간다.
• -npm run release가 안내하는 gh release create 명령은 notes 파일 경로를 셸 인용으로 출력한다.
• -docs/operations/monitoring.md의 엔드포인트 표에 /health 행을 싣고, /metrics가 Bearer 없이 401을 돌려주며 /health/live와 /health/ready는 키 없이 호출함을 적는다.
• -벤치마크 CLI는 --no-seed 실행에서 --save-baseline을 거부할 때 --no-seed를 사유로 안내한다.
• -tools/list는 recall, context, remember 순으로 앞에 두고 나머지를 이름 오름차순으로 돌려준다. 세션과 키가 달라도 노출되는 도구의 상대 순서가 같다. recall의 asOf 설명은 시간 근접 랭킹의 기준 시각이며 기간 필터가 아니라고 적고, 기간 한정은 timeRange를 안내한다.
• -POST /v1/internal/model/nothing/keys의 permissions는 read, write로만 이뤄진 비어 있지 않은 배열이어야 하고 생략하면 기본 권한을 쓴다. 빈 배열, null, 그 밖의 값은 400이다.
• -amend의 content는 remember와 같은 상한(4000자, 초과 시 -32602)을 따르고 민감 정보를 마스킹하며 300자(episode는 1000자)를 넘으면 잘라 저장한다. 변경으로 새로 생긴 PolicyRules 위반은 validation_warnings로 알리고, hard gate 키에서는 갱신하지 않고 도구 응답 { "success": false, "error": "policy_violation: ..." }로 돌려준다.
• -batch_remember는 항목마다 같은 관문을 거치고, 경고는 성공한 항목의 results[i].validation_warnings로, hard gate 거부는 항목의 error로 돌려준다.
• -관리 가져오기와 CLI 가져오기는 FragmentWriter.insert로 행을 기록해 content_hash(본문 전체 sha256)와 유형별 importance 상한을 채운다. 같은 본문이 이미 있는 행은 skipped, 관문이 받아들이지 않은 행과 행의 값 때문에 DB가 거부한 행(type, assertion_status CHECK 제약 등)은 errors로 세고 다음 행을 계속 가져온다.
• -CLI remember 로컬 모드는 서버와 같은 관문과 FragmentWriter로 한 트랜잭션에 기록한다. 같은 본문이 이미 있으면 새 행 없이 그 파편의 id를 출력하고, 출력의 importance는 요청 값이다.
• -통합 분할 자식은 부모의 key_id와 workspace로 관문(entry consolidate_split)을 거쳐 마스킹과 길이 상한을 받고 부모의 workspace를 물려받는다.
• -여러 파편 행을 갱신하거나 지우는 쓰기(접근 기록, 연결 파편 접근, 감쇠와 utility 묶음 갱신, 임베딩 기록, 링크 정리, 활성화 전파, 사례 보상, GC 삭제)는 한 트랜잭션에서 id 순 잠금 문장을 먼저 실행하고 잠근 행만 별도 문장으로 쓴다.
• -remember(scope=session)는 영구 저장과 같은 쓰기 관문(마스킹, 절삭, 정책, 거부)을 거친다. 세션 종합은 세션 ID가 같아도 호출한 키와 에이전트의 작업 기억 항목만 모으고 비운다(Redis 항목 포함).
• -amend로 본문을 바꾸면 estimated_tokens를 새 본문의 토큰 수로 기록한다.
• -관리 가져오기의 JSON 본문 상한은 2 MiB이고, Content-Type이 application/x-ndjson 또는 application/jsonl인 export 파일 본문은 64 MiB까지 받는다. 초과하면 413이다.
• -가져오기 dryRun(CLI --dry-run)은 DB에 연결해 같은 경로로 처리한 뒤 되돌리므로 집계가 실제 실행과 같다. 관문 지표는 남기지 않는다.
• -scripts/backfill-reflect-workspace.js는 대상 workspace에 같은 본문 파편이 이미 있는 파편을 옮기지 않는다.
• -중복 판정과 scripts/ops/finish-dedup-scope.mjs의 키 단위 색인 확인은 두 이름 묶음(uq_frag_hash_per_key, uq_frag_hash_master와 같은 정의의 fragments_new_key_id_content_hash_idx, fragments_new_content_hash_idx)을 모두 키 단위 색인으로 본다. 마무리 스크립트는 정의가 같은 쪽을 지우고, 정의가 다른 같은 이름의 색인은 지우지 않고 알린다.
• -API 키 권한 목록(POST /keys, PUT /keys/:id/permissions)은 read, write 중 하나 이상과 표지 권한 trusted_origin, anchor, review_off, review_all(검토 방식은 하나만)을 받는다. 빈 배열과 표지 권한만 있는 배열은 400이다. 권한 변경은 변경 전후 권한을 감사 기록에 남긴다.
• -context의 앵커 주입 줄은 MEMENTO_ANCHOR_PERMISSION이 off가 아니면 비식별 주체 표지([k:xxxx], 마스터 앵커는 [master])를 붙이고, 응답 앵커 파편은 key_id 대신 principal을 싣는다.
• -관리 API는 요청마다 라우트 표의 요구 능력을 판정한다. 마스터 키와 마스터 키 로그인 세션은 owner로 모든 라우트를 쓴다. 파편 이력과 /export는 판정 범위가 전체일 때만 열린다.

Removed

• -lib/symbolic/SymbolicOrchestrator.js, lib/symbolic/rules/index.js, lib/symbolic/rules/v1/claim-conflict.js, link-integrity.js, policy.js, 저장소 어댑터 lib/storage/와 각각의 시험, 이 모듈들의 문서 서술. lib/symbolic/rules/v1/explain.js와 proactive-gate.js는 남는다. MEMENTO_STORAGE, MEMENTO_SYMBOLIC_TIMEOUT_MS, MEMENTO_SYMBOLIC_MAX_CANDIDATES를 사용하는 처리가 없으며 설정해도 동작에 영향이 없다.