CLI

개요

bin/memento.js는 서버 없이 터미널에서 메모리 서버를 운영·조회할 수 있는 CLI 진입점이다. 전역 설치 시 anchormind 명령으로 실행하며, memento-mcp 명령도 동일하게 동작한다.

node bin/memento.js <command> [options]
# 또는
npm run cli -- <command> [options]

모든 명령은 .env 파일의 DATABASE_URL 등 환경변수를 읽는다. 실행 전 환경변수를 로드한다.

# 환경변수 로드 후 실행 예시
export $(grep -v '^#' .env | grep '=' | xargs)
node bin/memento.js stats

전역 플래그

모든 서브명령에서 공통으로 사용할 수 있는 플래그다.

플래그	설명
`--help`, `-h`	서브명령별 상세 도움말 출력
`--format table\|json\|csv`	출력 포맷. TTY 환경에서는 기본 `table`, 파이프/리다이렉트 환경에서는 `json`
`--json`	`--format json` 별칭 (하위 호환)
`--remote URL`	원격 MCP 서버 URL. 미지정 시 `MEMENTO_CLI_REMOTE` 환경변수 사용
`--key KEY`	원격 서버 인증용 Bearer API 키. 미지정 시 `MEMENTO_CLI_KEY` 환경변수 사용
`--timeout ms`	원격 HTTP 요청 타임아웃 (기본: 30000ms)
`--verbose`	에러 시 스택 트레이스 출력

원격 접속 환경변수

변수	설명
`MEMENTO_CLI_REMOTE`	`--remote` 미지정 시 사용할 MCP 서버 URL
`MEMENTO_CLI_KEY`	`--key` 미지정 시 사용할 API 키

서브명령 분류

local-only (원격 접속 불가)

serve, migrate, cleanup, backfill, health, update, export, import, benchmark 는 직접 DB / 프로세스에 접근하는 명령이므로 --remote 플래그와 함께 사용하면 에러를 반환한다.

원격 지원

recall, remember, stats, inspect 는 --remote URL --key KEY로 원격 MCP 서버를 경유하여 실행할 수 있다.

명령어 목록

커맨드	설명	원격 지원
`serve`	MCP 서버 시작	아니오
`migrate`	DB 마이그레이션 실행	아니오
`cleanup [--execute]`	노이즈 파편 정리 (기본 dry-run)	아니오
`backfill`	누락된 임베딩 백필	아니오
`stats`	파편/앵커/토픽 통계	예
`health`	DB/Redis/임베딩 연결 진단	아니오
`recall <query>`	터미널 recall	예
`remember <content>`	터미널 remember	예
`inspect <id>`	파편 상세 + 1-hop 링크	예
`session <sub>`	세션 list / show / delete / rotate (master key 필요)	예
`update [--execute] [--redetect]`	업데이트 확인 및 적용 (기본 dry-run)	아니오
`export [--topic x] [--type t]`	파편 JSONL 덤프	아니오
`import [--input FILE]`	JSONL 흡수 (파일 또는 stdin)	아니오
`completion <shell>`	bash/zsh 보완 스크립트 출력	예
`benchmark [--goldset FILE]`	골드셋 기반 회상 품질 계측	아니오

명령어 상세

serve

MCP 서버를 포그라운드로 시작한다.

node bin/memento.js serve
# 또는
npm start

PORT 환경변수로 포트 지정 (기본: 57332).

도움말:

node bin/memento.js serve --help

migrate

lib/memory/migrations/migration-*.sql 파일을 순서대로 실행한다. 이미 적용된 마이그레이션은 건너뛴다.

node bin/memento.js migrate
# 또는
npm run migrate

적용 이력은 agent_memory.schema_migrations 테이블에 기록된다.

도움말:

node bin/memento.js migrate --help

cleanup

util_score, importance, 비활성 기간 조건을 만족하는 노이즈 파편을 삭제한다.

node bin/memento.js cleanup           # dry-run (미리보기만)
node bin/memento.js cleanup --execute  # 실제 삭제 실행

직접 실행 대안:

node scripts/cleanup-noise.js --dry-run
node scripts/cleanup-noise.js --execute

backfill

임베딩이 없는 기존 파편에 임베딩을 생성한다. 임베딩 API 키 또는 로컬 transformers provider가 필요하다.

node bin/memento.js backfill
# 또는
npm run backfill:embeddings

stats

파편 수, 앵커 수, 토픽별 분포 등 현황을 출력한다.

# TTY 환경 — table 포맷 (기본)
node bin/memento.js stats

# JSON 포맷
node bin/memento.js stats --format json

# CSV 포맷
node bin/memento.js stats --format csv

# --json 별칭 (--format json 동일)
node bin/memento.js stats --json

# 원격 서버 조회
node bin/memento.js stats --remote https://memento.anchormind.net/mcp --key mmcp_xxx

출력 예시 (--format table):

fragments   anchors   topics
----------  --------  ------
1204        38        12

출력 예시 (--format json):

{"fragments": 1204, "anchors": 38, "topics": 12}

도움말:

node bin/memento.js stats --help

health

DB 연결, Redis 상태, 임베딩 provider 동작 여부를 진단한다.

node bin/memento.js health
node bin/memento.js health --format json

recall

터미널에서 파편 검색을 실행한다. 서버가 실행 중이지 않아도 로컬 DB에서 직접 동작한다. --remote 옵션으로 원격 서버를 경유할 수도 있다.

# 기본 검색
node bin/memento.js recall "검색어"

# 옵션 조합
node bin/memento.js recall "nginx 에러" --topic my-project --limit 5

# 시간 범위 필터
node bin/memento.js recall "2026-01-01 이후 기록" --time-range 2026-01-01,2026-12-31

# 출력 포맷 지정
node bin/memento.js recall "검색어" --format table
node bin/memento.js recall "검색어" --format json
node bin/memento.js recall "검색어" --format csv

# 원격 서버 경유
node bin/memento.js recall "검색어" --remote https://memento.anchormind.net/mcp --key mmcp_xxx

# 환경변수로 원격 설정 후 사용
MEMENTO_CLI_REMOTE=https://memento.anchormind.net/mcp MEMENTO_CLI_KEY=mmcp_xxx \
  node bin/memento.js recall "검색어"

옵션:

플래그	설명
`--topic <t>`	주제 필터
`--type <t>`	파편 유형 필터 (fact, error, procedure, decision, preference, episode)
`--limit <n>`	반환 건수 상한 (기본: 10)
`--time-range from,to`	날짜 범위 필터 (ISO 8601)

도움말:

node bin/memento.js recall --help

remember

터미널에서 파편을 저장한다. --remote 옵션으로 원격 서버에 저장할 수 있다.

# 기본 저장
node bin/memento.js remember "PostgreSQL 연결 시 pg_hba.conf 설정 필요" --topic infra --type fact

# 절차 저장
node bin/memento.js remember "배포 완료" --topic deploy-2026 --type procedure

# idempotencyKey 지정 (중복 저장 방지)
node bin/memento.js remember "nginx 재시작 후 443 포트 정상" --topic infra --type fact \
  --idempotency-key "infra-nginx-restart-2026-04-20"

# 원격 서버에 저장
node bin/memento.js remember "배포 완료" --topic deploy-2026 --type procedure \
  --remote https://memento.anchormind.net/mcp --key mmcp_xxx

옵션:

플래그	설명
`--topic <t>`	주제 태그 (권장)
`--type <t>`	파편 유형 (fact, error, procedure, decision, preference, episode)
`--importance <n>`	중요도 0.0~1.0
`--idempotency-key <k>`	동일 키가 있으면 저장 건너뜀 (멱등성 보장)

도움말:

node bin/memento.js remember --help

inspect

파편 ID로 전체 메타데이터와 1-hop 링크를 출력한다.

node bin/memento.js inspect frag-00abc123
node bin/memento.js inspect frag-00abc123 --format json
node bin/memento.js inspect frag-00abc123 --format table

# 원격 서버 조회
node bin/memento.js inspect frag-00abc123 --remote https://memento.anchormind.net/mcp --key mmcp_xxx

도움말:

node bin/memento.js inspect --help

session

활성 세션을 조회하고 강제 종료하거나 ID를 재발급한다. 모든 서브명령은 master key(MEMENTO_ACCESS_KEY)를 요구한다. 원격 모드(--remote / --key)로 지정하면 Admin HTTP API를 직접 호출한다.

서브명령 4종.

# 활성 세션 목록 (기본 limit 50)
memento-mcp session list [--limit N] [--workspace X] [--format table|json|csv]

# 단일 세션 상세 (keyId, createdAt, lastAccessedAt, expiresAt, heartbeat)
memento-mcp session show <sessionId>

# 세션 강제 종료 (autoReflect 포함)
memento-mcp session delete <sessionId>

# 세션 ID 회전 (session fixation 대응)
memento-mcp session rotate <sessionId> [--reason "suspected_leak"]

session rotate는 Redis에 저장된 세션 데이터를 유지하면서 ID만 재바인딩한다. 진행 중이던 작업과 기억 파편은 영향 없다. reason은 최대 128자 감사 로그용 문자열이며 기본값은 explicit_rotate.

rotate 엔드포인트 정책:

HTTP: POST /session/rotate (body: { "reason": "..." })
인증: Authorization: Bearer <API key or master key> + Mcp-Session-Id 헤더로 대상 세션 지정
CSRF 방어: Origin 헤더 필수. 누락 시 403
Rate limit: IP당 분당 MEMENTO_ROTATE_RATE_LIMIT_PER_MIN (기본 5) 초과 시 429
메트릭: mcp_session_rotation_total (label: reason)

CLI는 초과 시 표준 에러로 HTTP 429를 출력한다. 원격 모드에서도 동일한 rate-limit이 적용된다.

출력 예시 (list, table 포맷):

SESSION ID                       KEY ID    WORKSPACE  CREATED              LAST ACCESSED        TTL (min)
----------------------------------------------------------------------------------------------------------
aabbcc11-2233-4455-6677-8899ddee  default   paysvc     2026-04-21T10:12:03  2026-04-21T12:34:56  41520
bbccdd22-3344-5566-7788-99aaeeff  mmcp_xx   -          2026-04-21T11:00:00  2026-04-21T12:30:00  41500

--help로 서브명령별 세부 옵션 확인 가능.

memento-mcp session --help
memento-mcp session list --help
memento-mcp session rotate --help

update

서버 업데이트를 확인하고 선택적으로 적용한다.

node bin/memento.js update              # dry-run: 사용 가능한 업데이트 확인
node bin/memento.js update --execute    # 업데이트 적용
node bin/memento.js update --redetect   # 설치 방식 재탐지 후 업데이트

도움말:

node bin/memento.js update --help

export

파편을 JSONL(한 줄당 한 파편) 형식으로 덤프한다. 백업·이관용.

node bin/memento.js export --topic memento-mcp --type fact > out.jsonl
node bin/memento.js export --since 2026-04-01 --output backup.jsonl
node bin/memento.js export --key mmcp_xxx --limit 500

주요 옵션: --topic, --type, --since <ISO>, --limit <n>, --output <FILE>, --json (배열 출력).

도움말:

node bin/memento.js export --help

import

JSONL 파일 또는 stdin에서 파편을 읽어 fragments 테이블에 적재한다.

node bin/memento.js import --input out.jsonl
cat out.jsonl | node bin/memento.js import
node bin/memento.js import --input out.jsonl --idempotent --dry-run

--idempotent는 idempotency_key 또는 id 충돌 시 INSERT를 건너뛴다. --dry-run은 검증만 수행한다.

도움말:

node bin/memento.js import --help

completion

bash/zsh 자동완성 스크립트를 표준 출력으로 인쇄한다.

node bin/memento.js completion bash >> ~/.bashrc
node bin/memento.js completion zsh  >> ~/.zshrc
source <(node bin/memento.js completion bash)

지원 셸: bash, zsh(bash-compat).

도움말:

node bin/memento.js completion --help

원격 접속 사용 예시

--remote와 --key를 직접 지정하거나 환경변수로 설정한다.

# 직접 지정
node bin/memento.js recall "배포 기록" \
  --remote https://memento.anchormind.net/mcp \
  --key mmcp_xxx

# 환경변수로 설정 후 사용
export MEMENTO_CLI_REMOTE=https://memento.anchormind.net/mcp
export MEMENTO_CLI_KEY=mmcp_xxx
node bin/memento.js recall "배포 기록"
node bin/memento.js stats
node bin/memento.js remember "배포 완료" --topic deploy --type procedure

serve, migrate, cleanup, backfill, health, update 명령에서 --remote를 사용하면 에러가 반환된다.

출력 포맷 상세

포맷	특징	권장 상황
`table`	사람이 읽기 쉬운 정렬 표	TTY 터미널 직접 확인
`json`	기계 판독 가능한 JSON	파이프 처리, 스크립트
`csv`	쉼표 구분 값	스프레드시트, awk 처리

TTY 감지: 파이프나 리다이렉트 환경(| jq, > out.txt)에서는 --format을 명시하지 않아도 자동으로 json을 선택한다.

recall --format csv 출력 예시:

id,type,topic,importance,content
frag-00abc123,fact,infra,0.80,"PostgreSQL 연결 시 pg_hba.conf 설정 필요"
frag-00def456,procedure,deploy-2026,0.70,"배포 완료"

npm 스크립트 연동

스크립트	실행 내용
`npm start`	`node server.js` (서버 시작)
`npm run cli -- <args>`	`node bin/memento.js <args>`
`npm run migrate`	`node scripts/migrate.js`
`npm run backfill:embeddings`	`node scripts/backfill-embeddings.js`
`npm test`	node:test 단위 테스트
`npm run test:integration`	통합/E2E 테스트 일괄 실행
`npm run test:integration:llm`	LLM provider 통합 테스트 순차 실행

스크립트 단독 실행

임베딩 일관성 검사

DATABASE_URL=$DATABASE_URL EMBEDDING_DIMENSIONS=1536 \
  node scripts/check-embedding-consistency.js

fragments와 morpheme_dict 두 테이블의 실제 벡터 차원이 EMBEDDING_DIMENSIONS 설정과 일치하는지 확인한다. 불일치 시 FAIL을 출력하고 migration-007 재실행 가이드를 제공한다.

벡터 차원 변경 (migration-007 재실행)

임베딩 제공자 변경 또는 EMBEDDING_DIMENSIONS 변경 후 실행한다.

EMBEDDING_DIMENSIONS=384 DATABASE_URL=$DATABASE_URL \
  node scripts/post-migrate-flexible-embedding-dims.js

fragments와 morpheme_dict 테이블의 벡터 컬럼 차원을 동시에 갱신한다. 스킵 판정은 (타입, 선언 차원) 쌍으로 하며, --dry-run으로 변환 대상만 미리 확인할 수 있다. 변환은 테이블별 트랜잭션으로 실행되어 중간 실패 시 롤백된다. 변환 후 fragments는 서버 스케줄러가 자동 재임베딩하지만 morpheme_dict는 node scripts/backfill-morpheme-dict.js를 별도 실행해야 한다.

임베딩 백필

기존 파편의 임베딩이 없거나 차원이 변경된 경우 재생성한다.

node scripts/backfill-embeddings.js

L2 정규화

임베딩 벡터를 L2 정규화한다. 제공자 전환 후 1회 실행하면 된다.

DATABASE_URL=$DATABASE_URL node scripts/normalize-vectors.js

benchmark

골드셋 (저장문, 질의) 패러프레이즈 쌍으로 회상 품질을 정량 측정한다. 저장문을 격리 스코프에 적재하고 질의를 실행해 정답 파편의 순위를 구한 뒤 Recall@k, MRR, 지연을 산출하고, 실행이 끝나면 적재분을 회수한다.

node bin/memento.js benchmark
node bin/memento.js benchmark --repeat 3 --json
node bin/memento.js benchmark --save-baseline scripts/baseline-recall.json
node bin/memento.js benchmark --baseline scripts/baseline-recall.json

주요 옵션: --goldset <path>(기본 tests/fixtures/recall-goldset.jsonl), --baseline <path>, --save-baseline <path>, --limit <n>, --repeat <n>, --synthetic, --page-size <n>, --key-scope isolated|corpus, --no-seed, --no-cleanup.

--synthetic은 적재한 파편에 합성 역질의를 생성한 뒤 평가한다. 역질의 증강의 효과를 통제 변수로 재려는 목적이며, 파편당 LLM 호출이 발생하므로 기본 실행에는 포함되지 않는다.

--baseline으로 비교했을 때 회귀가 감지되면 종료 코드 2를 반환한다. Recall 하락 허용치는 2pp, 지연 p95 증가 허용치는 15%다. 같은 적재분 안에서는 회차 간 편차가 0이지만 적재를 다시 하면 1pp 안팎으로 움직이므로, 허용치를 그보다 좁게 잡으면 게이트가 잡음에 반응한다.

측정 모드는 두 가지다.

모드	후보 집합	재현성	용도
`isolated` (기본)	적재한 골드셋 파편만	회차 간 동일	변경 전후 귀속 비교
`corpus`	운영 파편과 경쟁	코퍼스 변화에 따라 달라짐	실제 건초더미에서의 체감 확인

--repeat는 한 번 적재한 뒤 평가만 반복해 중앙값과 회차 간 편차를 함께 보고한다. 적재 직후에는 형태소 등록과 자동 링크 생성이 끝나기를 기다리는 안정화 단계가 들어가며, 이 대기가 없으면 같은 코드에서도 회차마다 순위가 흔들린다.

도움말:

node bin/memento.js benchmark --help

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI

개요

전역 플래그

원격 접속 환경변수

서브명령 분류

local-only (원격 접속 불가)

원격 지원

명령어 목록

명령어 상세

serve

migrate

cleanup

backfill

stats

health

recall

remember

inspect

session

update

export

import

completion

원격 접속 사용 예시

출력 포맷 상세

npm 스크립트 연동

스크립트 단독 실행

임베딩 일관성 검사

벡터 차원 변경 (migration-007 재실행)

임베딩 백필

L2 정규화

benchmark