백테스팅 피드백 루프

N 시간 지난 실행 거래에 대해 P&L 결과를 계산하고 EvaluationLoop + MethodologyStore 로 되먹여, Wilson-LB 졸업 메커니즘이 실제 승/패 신호를 축적하도록 하는 주기적 작업입니다. 기본적으로 완전히 비활성(dark)입니다 (BACKTEST_ENABLED=false). 과거 거래를 재생하거나 지난 결정을 재실행하지 않으며, 실제로 세션 내에서 실행된 행만 평가합니다. 롤아웃 프로토콜: 1. BACKTEST_ENABLED=true + BACKTEST_DRY_RUN=true 로 1주간 실행 2. shadow_runs WHERE facet='backtest_outcome' 검사 3. 결과가 깨끗해 보이면 BACKTEST_DRY_RUN=false 로 전환 4. 마지막으로 LEARNING_RECORD_USAGE=true 로 전환 — Wilson 카운터 업데이트를 활성화

`BACKTEST_ENABLED`

runner + 스케줄러의 마스터 스위치. false (기본값) = runner 를 전혀 생성하지 않으며 cron 타이머도 등록하지 않습니다. 런타임 비용이 0 입니다. true = runner 를 생성하고 스케줄러가 BACKTEST_CRON_HOURS 시간마다 실행됩니다. 아래의 DRY_RUN 은 여전히 적용됩니다.

형식: true / false.
설정 위치: 설정 → 환경설정 (schema 키)

`BACKTEST_DRY_RUN`

true 이면 runner 가 결과를 계산하여 shadow_runs(facet='backtest_outcome') 에 기록하지만 updateTradeOutcome 나 recordUsage 는 호출하지 않습니다. 최소 한 번의 전체 cron 주기 동안 shadow 행을 점검한 뒤에만 false 로 전환하십시오.

형식: true / false.
설정 위치: 사용자 대상 설정 아님

`BACKTEST_MIN_TRADE_AGE_MS`

거래가 백테스트 평가 대상이 되기까지의 최소 경과 시간(ms). 결과가 형성되려면 시간이 필요하며 5분 지평은 노이즈에 불과합니다. ReviewEngine 의 minTradeAgeForEvalMs 로 전달됩니다. 기본값 86400000 (24h).

형식: 양의 정수(ms).
설정 위치: 사용자 대상 설정 아님

`BACKTEST_OUTCOME_HORIZON_HOURS`

거래 created_at 이후 결과 가격을 샘플링하는 시점까지의 시간(시간 단위). +5% in 24h = 24. 평가자가 윈도우 길이를 알 수 있도록 기록되는 결과 문자열에도 동일하게 반영됩니다. Sprint 6 에서는 단일 전역 값입니다(TODOS #9 에서 거래 유형별 튜닝을 추적). 기본값 24.

형식: 양의 정수(시간 단위).
설정 위치: 사용자 대상 설정 아님

`BACKTEST_BATCH_LIMIT`

runner 가 한 번 실행할 때 가져오는 최대 대기 행 수. ReviewEngine 의 maxEvalsPerBatch 로 전달됩니다. 실행당 LLM 비용을 제한하려면 낮추고, 대기 큐가 계속 쌓여 있으면 높이십시오. 기본값 20.

형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`BACKTEST_CRON_HOURS`

스케줄러 실행 간격. runner 는 setInterval(… * 3600_000) 을 통해 호출되며, 타이머는 unref() 를 사용하므로 그 자체로는 프로세스를 살려두지 않습니다. 부동소수점을 허용하며 0.017(1분) 미만의 값은 위로 상향 조정됩니다. 기본값 24.

형식: 양수(시간 단위).
설정 위치: 사용자 대상 설정 아님

`BACKTEST_PRICE_PROVIDER`

디버깅을 위해 단일 과거 가격 소스를 강제합니다. auto 는 자산 클래스에 따라 라우팅합니다(crypto → Hyperliquid → Yahoo -USD 폴백; stock/unknown → Yahoo; stablecoin → 1.0). Yahoo 심볼 정규화가 의심되면 hyperliquid 로 고정하고, Hyperliquid 가 rate-limit 에 걸리면 yahoo 로 고정하십시오.

형식: auto / hyperliquid / yahoo.
설정 위치: 사용자 대상 설정 아님

`BACKTEST_MAX_COST_USD_PER_RUN`

호출당 하드 비용 상한. runner 는 evaluatePacked 전후로 BudgetTracker.getDailySpend("learning") 를 스냅샷하며, 그 차이가 이 값을 초과하면 실행이 status=stopped_budget 을 반환합니다. 0 은 상한을 비활성화합니다. 기본값 2.00.

Stackable: BudgetTracker 의 기존 일간/월간 상한은 그대로 적용됩니다.
형식: 음이 아닌 부동소수점(USD).
설정 위치: 사용자 대상 설정 아님

`LEARNING_RECORD_USAGE`

true 이면 EvaluationLoop 이 평가된 거래마다 trade_history.methodology_ids 를 확인합니다. Phase 1.2a 중복 제거(codex R1 P1)는 귀속된 방법론이 하나라도 있는 거래에 대해 recordUsage 호출을 의도적으로 억제합니다 — 그러한 거래는 대신 case-attribution.ts 가 Wilson 학습을 수행합니다. 오늘날 귀속이 없는 거래도 이 경로에서는 Wilson 신호를 생성하지 않으며, Wilson 업데이트는 전적으로 case-attribution 을 통해 이루어집니다.

따라서 이 환경 변수는 이제 학습 게이트가 아니라 관측성(observability) 게이트입니다:
true 로 전환하면 귀속된 거래마다 wilson_dedup_skip 로그 라인이 남아,
운영자가 프로덕션에서 중복 제거가 실제로 동작하는지 확인할 수 있습니다.
기존의 "평가된 모든 거래에 일괄적으로 recordUsage 를 기록"하던
동작은 사라졌습니다.
형식: true / false.
설정 위치: 설정 → 환경설정 (schema 키)

`LEARNING_TUNING_ENABLED`

src/learning/methodology-store.ts 의 LEARNING_CONFIG 에 대해 더 나은 값을 탐색하는 오프라인 베이지안 최적화 튜닝 하네스의 마스터 게이트. 이 하네스는 오프라인 도구이며(minara learning replay + tools/tuning/ 의 Python BO 를 통해 실행), 요청 경로의 일부가 절대 아닙니다. 이 게이트는 프로덕션에서 replay CLI 가 실수로 호출되는 것을 방지하기 위해 존재합니다.

사용처: src/gateway/learning-cli.ts — replay 하위 명령은
이 값이 true 가 아니면 { skipped: "tuning_disabled" } 로
단락(short-circuit)합니다.
Exception: minara learning stats 는 순수 읽기 전용이며(데이터 준비도 보고를 위한
trade_history + methodologies 대상 SQL SELECT), 이
게이트와 무관하게 실행됩니다. 운영자는 튜닝 실행을 정당화할 만큼
충분한 Sprint 6 데이터가 축적되었는지에 대한 지속적인 가시성이 필요합니다
(목표: 고유 방법론 id ≥20개를 포함하는 평가된 거래
≥100건).
Rollout: 이 값은 다음 조건이 충족될 때까지 false 로 유지됩니다: (a) Sprint 6 롤아웃 완료
(LEARNING_RECORD_USAGE=true), (b) minara learning stats 가
READY_FOR_BO=true 를 보고, (c) 사람 운영자가 명시적으로
튜닝 세션을 시작. 프로덕션에서 false 로 두는 것이 기본적으로 안전한
자세입니다.
형식: true / false.
설정 위치: 사용자 대상 설정 아님

Phase 1 — Decision Capture (advice BUY/SELL/HOLD)

결정 캡처 훅은 에이전트 루프의 턴 종료 시점에 실행됩니다. 턴이 투자 조언을 포함하면(9개 조언 시나리오 중 하나가 활성이거나, 에이전트 응답에 BUY/SELL/HOLD 키워드 + 티커가 매칭될 때), 독립적인 요약기 LLM 호출이 구조화된 {asset, decision, confidence, quoted_price} 튜플을 추출하여 decision_history 에 저장합니다. 이 데이터는 Phase 2 다중 지평 백테스트와 Phase 6 방법론 인스턴스 BO 튜닝에 공급됩니다. 요약기는 항상 fire-and-forget(비동기)입니다. 사용자가 체감하는 턴 지연은 변하지 않습니다. 실패 시 로그를 남기고 행을 조용히 버립니다.

`DECISION_CAPTURE_ENABLED`

Phase 1 캡처의 마스터 스위치. false(기본값)이면 턴 종료 훅이 어떤 사전 필터나 LLM 호출도 실행하지 않고 즉시 반환합니다. true 로 전환하면 decision_history 채우기가 시작됩니다. 언제든 안전하게 전환할 수 있으며 데이터 마이그레이션이 필요 없습니다.

사용처: src/learning/decision-capture/capture-hook.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 설정 → 환경설정 (schema 키)

`DECISION_SUMMARIZER_MODEL`

의사결정 요약기(summarizer) LLM 호출에 사용할 모델. 기본값은 비용 효율을 위해 Claude Haiku 4.5 를 대상으로 합니다(입력 800 + 출력 200 토큰 기준 턴당 약 $0.002). 통계에서 요약기 커버리지 비율이 70% 미만이면 Sonnet 으로 올릴 수 있습니다.

사용처: src/learning/decision-capture/summarizer.ts.
미설정 시: 기본값 claude-haiku-4-5-20251001.
형식: Anthropic 모델 id.
설정 위치: 사용자 대상 설정 아님

`DECISION_SUMMARIZER_TIMEOUT_MS`

단일 요약기 호출의 하드 타임아웃. 요약기는 fire-and-forget 로 실행되며, 타임아웃이 발생하면 경고 로그를 남기고 재시도 없이 해당 의사결정을 폐기합니다.

사용처: src/learning/decision-capture/summarizer.ts.
미설정 시: 기본값 15000.
형식: 양의 정수(ms).
설정 위치: 사용자 대상 설정 아님

`DECISION_CAPTURE_SYNC_MODE`

true 이면 훅에서 반환하기 전에 요약기를 await 합니다(턴 지연이 추가됨). 결정적(deterministic) 테스트 / CI 전용이며, 프로덕션에서는 false 로 유지해야 합니다.

사용처: src/learning/decision-capture/capture-hook.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 사용자 대상 설정 아님

`DECISION_CAPTURE_HEURISTIC_ENABLED`

Tier 2 정규식 사전 필터. true(기본값)이면 조언 시나리오가 활성화되지 않았더라도 에이전트의 최종 응답에 BUY/SELL/HOLD 키워드 + 자산 티커가 포함된 턴도 훅이 캡처합니다. false 로 설정하면 캡처를 조언 시나리오 턴으로만 엄격히 제한합니다.

사용처: src/learning/decision-capture/classify-capture-source.ts.
미설정 시: 기본값 true(활성화).
형식: true / false.
설정 위치: 사용자 대상 설정 아님

`DECISION_CAPTURE_UNIVERSAL_SCAN`

Tier 3 옵트인 유니버설 스캔. true 이면 모든 턴이 요약기를 호출합니다(Tier 1/2 우회). 진단용 A/B 실행 전용이며, 상시 사용하면 요약기 예산이 약 4배로 늘어납니다. false 로 두는 것을 강력히 권장합니다.

사용처: src/learning/decision-capture/classify-capture-source.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 사용자 대상 설정 아님

Phase 2 — 다중 지평 결정 백테스트

DecisionBacktestRunner 는 나이가 max_horizon(1m 지평의 경우 기본 30일) 이상인 decision_history 행을 스캔하여 다음을 채웁니다: (a) HistoricalPriceProvider 에서 가져온 real_price_at_decision, 할루시네이션 플래그를 위해 agent_quoted_price 와 비교 (b) decision_outcomes 행 — 지평마다 하나씩 {1d, 3d, 1w, 1m} |agent_quoted - real|/real > HALLUCINATION_MAX_PRICE_DELTA_PCT 이면, 해당 결정은 state='skipped_halluc' 로 표시되어 다운스트림 학습에서 제외됩니다.

`DECISION_BACKTEST_ENABLED`

decision-history 다중 지평 백테스트 cron 의 마스터 스위치. 현재 릴리스에서는 실험적(EXPERIMENTAL) 입니다: 이제 runner 가 ReasoningQualityJudge(src/learning/backtest/reasoning-quality.ts 참조)를 연결하여, "에이전트가 HOLD 라고 했지만 시장이 상승"한 경우의 실패를 Wilson 업데이트에 직접 사용하지 않습니다 — 그러한 패턴은 에이전트가 직전 시장 움직임을 좇도록 학습시키기 때문입니다(즉 제품팀이 명시적으로 피하고자 하는 개인 투자자 행동). Phase 1 은 모든 의사결정을 no_judgment 으로 분류하는 no-op 기본 판정기를 제공하므로, 오늘 이 플래그를 true 로 전환하면 decision_outcomes 행을 채우고 판정 집계를 방출하기만 합니다; 이 경로에서는 어떤 방법론 Wilson 카운터도 증가하지 않습니다. cron 을 학습에 활용하려면 Phase 2 EvaluationProvider 가 실제 LLM-as-judge 를 제공할 때까지 기다리십시오. 그때까지는: - false(기본값): runner 는 no-op 입니다. - true(dry-run 전용 권장): decision_outcomes 를 채우고, 실행 요약에 판정을 집계하며, Wilson 은 절대 업데이트하지 않습니다.

사용처: src/learning/backtest/decision-runner.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 설정 → 환경설정 (schema 키)

`METHODOLOGY_LEARNING_CRON_ENABLED`

인프로세스 방법론 cron 오케스트레이터(sweep → 7일 case-attribution → synthesis)에 대한 옵트인. 설정하지 않으면(기본값) 에이전트는 자동 스케줄링을 하지 않으며, 운영자가 시스템 cron / launchctl / systemd 에서 minara learning cron 으로 루프를 진행시킵니다. true 로 설정하면 오케스트레이터가 METHODOLOGY_LEARNING_CRON_INTERVAL_MS(기본 6h)마다 실행됩니다. 실행된 거래에 대한 Wilson 학습은 이 게이트 아래에서 case-attribution 을 통해 흐르므로, 신호가 노이즈가 되지 않도록 활성 asset_class 당 실제 사례 ≥ 100건이 축적된 뒤에만 켜십시오.

사용처: src/app.ts + src/learning/methodology-cron.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 설정 → 환경설정 (schema 키)

`METHODOLOGY_LEARNING_CRON_INTERVAL_MS`

METHODOLOGY_LEARNING_CRON_ENABLED=true 일 때 cron 패스 사이의 간격(밀리초). 기본값은 21600000(6시간)입니다. 간격이 짧을수록 더 많은 신호를 만들어내지 못한 채 LLM 판정기 예산만 빠르게 소모합니다.

사용처: src/learning/methodology-cron.ts.
미설정 시: 기본값 21600000.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_ENABLED`

apps/agent/src/learning/experimental/tuning/ 하위의 실험적 방법론 튜닝(BO 플래너) 서브트리에 대한 옵트인. Phase 1.7 에서 이 코드를 기본 에이전트 부팅 경로 밖으로 옮겼는데, cycle-planner.ts 가 dry-run 계획만 방출하는 스텁이기 때문입니다 — BO 를 절대 실행하지 않으며 따라서 어떤 방법론도 변경하지 않습니다. minara learning tune-methodology --dry-run 으로 플래너의 tunability-score 출력을 확인하고 싶을 때만 true 로 전환하십시오; 실제 실행기는 이후 단계에서 제공됩니다.

사용처: src/gateway/learning-cli.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 설정 → 환경설정 (schema 키)

`DECISION_REPLAY_ENABLED`

apps/agent/src/learning/experimental/replay/ 하위의 실험적 decision-replay 서브트리에 대한 옵트인. 현재 decision-replay.ts 구현은 명시적으로 자리표시자(PLACEHOLDER)입니다(파일 헤더 참조) — 단순 가중 평균 보상을 반환할 뿐 임계값 인식 replay 를 수행하지 않습니다. 방법론 조정을 뒷받침하는 데 그 출력을 신뢰하지 마십시오. Phase 6+ 작업에서 자리표시자를 실제 엔진으로 교체합니다.

사용처: src/gateway/learning-cli.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 설정 → 환경설정 (schema 키)

`DECISION_BACKTEST_DRY_RUN`

true 이면 runner 가 decision_outcomes / decision_history 에 기록하지 않고, 대신 결과 + 플래그를 shadow_runs(facet='decision_outcome') 에 로깅합니다. 1주차 롤아웃 프로토콜입니다. shadow 행이 정상으로 보이는지 확인한 뒤 false 로 전환하십시오.

사용처: src/learning/backtest/decision-runner.ts.
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 사용자 대상 설정 아님

`DECISION_BACKTEST_HORIZONS`

<number><unit> 형식의 지평 사양 CSV 이며 단위는 h/d/w/m(시간/일/주/월)입니다. 예: 1d,3d,1w,1m. 각 지평은 의사결정당 decision_outcomes 에 한 행을 생성합니다. 최대 지평이 대기 중인 의사결정이 백테스트 대상이 되는 시점을 결정합니다.

사용처: src/learning/backtest/decision-runner.ts.
미설정 시: 기본값 1d,3d,1w,1m.
형식: 쉼표로 구분된 목록.
설정 위치: 사용자 대상 설정 아님

`DECISION_BACKTEST_CRON_HOURS`

runner 호출 사이의 간격.

사용처: src/app/backtest.ts (wireBacktest interval).
미설정 시: 기본값 24.
형식: 양수(시간 단위).
설정 위치: 사용자 대상 설정 아님

`DECISION_BACKTEST_MAX_AGE_DAYS`

의사결정 나이의 하드 상한. 이보다 오래된 행은 지평 채움 상태와 무관하게 건너뛰어, 무한한 백로그 증가를 방지합니다.

사용처: src/learning/backtest/decision-runner.ts.
미설정 시: 기본값 60.
형식: 양의 정수(일 단위).
설정 위치: 사용자 대상 설정 아님

`HALLUCINATION_MAX_PRICE_DELTA_PCT`

agent_quoted_price 가 설정되어 있고 real_price_at_decision 과 이 비율보다 크게 벗어나면, 해당 의사결정은 플래그가 지정되어 다운스트림 학습에서 제외됩니다. 0.05(5%)는 대부분의 도구 출력 지연으로 인한 오탐을 걸러내면서도 큰 조작은 여전히 잡아냅니다. 오래된 캐시가 흔하면 0.03 으로 조이고, HistoricalPriceProvider 자체가 노이즈가 많은 경우에만 0.10 으로 완화하십시오.

사용처: src/learning/backtest/decision-outcome-filler.ts.
미설정 시: 기본값 0.05.
형식: 양의 소수(0.01 = 1%).
설정 위치: 사용자 대상 설정 아님

Phase 3 — 보상 계산

보상 함수는 4개 지평 수익률 벡터(Phase 2)를 결정당 단일 스칼라로 변환합니다. 세 가지 규칙: BUY: pct_return 의 가중 평균 (가격 상승 시 보상 증가) SELL: -pct_return 의 가중 평균 (가격 하락 시 보상 증가) HOLD: 선형 중립 보상 — |return| < threshold 이면 양의 보상 (0 에서 1, threshold 에서 0 으로 감쇠). threshold 초과 시 선형 음수 (기회비용 / 놓친 움직임).

`DECISION_HORIZON_WEIGHTS_JSON`

보상 합계에서 지평별 가중치. 문자열화된 JSON 객체 {label: weight}. 누락된 label 은 가중치 0 을 받습니다. 기본값은 "중기 신호" 편향을 반영합니다 — 1w 가 가장 높고, 일일 노이즈 때문에 1d 가 가장 낮습니다.

사용처: src/learning/decision-reward/reward.ts rewardOptionsFromEnv().
미설정 시: 기본값 {"1d":0.15,"3d":0.25,"1w":0.35,"1m":0.25}.
형식: JSON 문자열.
예시(단기에 더 무게를 둠): DECISION_HORIZON_WEIGHTS_JSON='{"1d":0.35,"3d":0.30,"1w":0.25,"1m":0.10}'
설정 위치: 사용자 대상 설정 아님

`DECISION_HOLD_NEUTRALITY_THRESHOLD`

|pct_return| 이 이 값 미만이면 HOLD 승리로 계산됩니다. 0.02 = 2%. HOLD 보상을 완화하려면 올리고("변동성이 있어도 괜찮다"는 허용 폭 확대), 조이려면 낮추십시오(HOLD 는 거의 0에 가까운 움직임이어야 함).

사용처: src/learning/decision-reward/reward.ts rewardOptionsFromEnv().
미설정 시: 기본값 0.02.
형식: 양의 소수(0.01 = 1%).
설정 위치: 사용자 대상 설정 아님

Phase 6 — BO 튜닝 사이클

(template, asset_class) 별 방법론 임계값에 대한 오프라인 베이지안 최적화입니다. 주기적으로(cron) 실행되며, Phase 1-3 의 결정 보상을 읽어 튜닝된 임계값을 methodology_instances 에 씁니다. 완전히 비활성 상태로 안착되어 있어 활성화 전까지 런타임 비용이 0 입니다. tools/tuning/ 의 Python 하네스가 필요합니다.

`METHODOLOGY_INSTANCE_TUNING_ENABLED`

BO 사이클 오케스트레이터의 마스터 스위치. false(기본값)이면 스케줄되어 있어도 사이클은 no-op 입니다. Phase 1/2/3 데이터가 축적되고 minara learning stats 의 READY_FOR_BO=true 가 된 뒤에만 true 로 전환하십시오.

사용처: src/learning/experimental/tuning/cycle.ts (Phase 7 에서
연결 예정).
미설정 시: 기본값 false.
형식: true / false.
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_CRON_DAYS`

BO 사이클 호출 사이의 일수. 기본값은 7(주간)입니다. 값이 낮으면 단기 시장 노이즈에 과적합될 위험이 있고, 높으면 학습이 느려집니다.

사용처: src/app.ts (cron 연결, Phase 7).
미설정 시: 기본값 7.
형식: 양의 정수(일 단위).
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_MAX_BUCKETS_PER_CYCLE`

사이클당 상한. 적격 버킷은 tunability_score 로 순위가 매겨지며, 사이클마다 상위 N개만 Python BO 하네스로 전달됩니다.

사용처: src/learning/experimental/tuning/cycle.ts.
미설정 시: 기본값 10.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_PROFILES_PATH`

자산 클래스 프로필 JSON 의 경로 재정의. 클래스별로 BUILTIN_PROFILES 위에 얕은 병합(shallow merge)을 수행합니다. 어떤 클래스를 튜닝에서 완전히 제외하려면 값을 null 로 설정하십시오.

사용처: src/learning/experimental/tuning/asset-profiles.ts.
미설정 시: 기본값 $MINARA_DATA_DIR/methodology-tuning-profiles.json.
형식: 파일 시스템 경로(존재하지 않을 수 있으며, 그 경우 no-op).
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_MIN_DECISIONS_GLOBAL`

모든 프로필에 걸친 min_decisions 의 전역 하한(프로필별 값과 max 를 취함). 예를 들어 잘못된 롤아웃 이후처럼 긴급하게 조일 때 사용합니다.

사용처: src/learning/experimental/tuning/asset-profiles.ts.
미설정 시: 하한을 적용하지 않음.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_MIN_IMPROVEMENT_REL`

BO 이후 검사 #1 상대 개선 게이트(테스트 분할 평균 보상이 기준선을 이 비율만큼 초과해야 함). 0.05 = 5%.

사용처: src/learning/experimental/tuning/cycle.ts Phase 7.
미설정 시: 기본값 0.05.
형식: 양의 소수.
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_MAX_SENSITIVITY_DROP_10PCT`

BO 이후 검사 #2 좁은 정점(narrow-peak) 거부. 최적 후보의 ±10% 근방 점수가 이 비율보다 크게 떨어져서는 안 됩니다. 0.5 = 50%.

사용처: src/learning/experimental/tuning/cycle.ts Phase 7.
미설정 시: 기본값 0.5.
형식: (0, 1] 범위의 소수.
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_PARAM_BOUND_REL`

템플릿 기본값의 배수로 표현한 BO pbounds 절반 폭. 0.5 는 각 파라미터에 대해 경계 = [기본값 × 0.5, 기본값 × 1.5] 를 의미합니다.

사용처: src/learning/experimental/tuning/cycle.ts Phase 7.
미설정 시: 기본값 0.5.
형식: 양의 소수.
설정 위치: 사용자 대상 설정 아님

`METHODOLOGY_TUNING_MIN_CAPTURE_CONFIDENCE`

BO replay 하네스는 capture_confidence 가 이 임계값 이상인 의사결정만 고려합니다. 0.3 은 세 가지 tier 를 모두 포함하며(advice_scenario, heuristic_match, summarizer_promoted), 0.6+ 로 올리면 고신호 의사결정으로만 제한됩니다.

사용처: src/learning/experimental/replay/decision-replay.ts (Phase 7).
미설정 시: 기본값 0.3.
형식: [0, 1] 범위의 소수.
설정 위치: 사용자 대상 설정 아님

선호 진화 (M2: Financial Auto-Memory)

최근 사용자 메시지를 스캔하여, 모델에게 이를 지속적인 선호 (kind ∈ {personal_style, behavioral_preference})로 클러스터링하도록 요청하고, 쿨다운 창마다 한 번씩 카드 형태의 졸업 요청을 노출하는 주기적 LLM 주도 제안기입니다. AutoClaw 의 주간 진화 루프를 본떴으며 주당 1-3건 졸업의 소프트 상한을 둡니다. M2 경계: hard_constraint 후보는 behavioral_preference 로 강등되며 도구 수준에서 자동 적용되지 않습니다 — 도구 수준 시행은 키워드 스캐너와 함께 M3 에서 안착합니다. 수동 /preferences approve|reject|deprecate 는 운영자 재정의를 위해 마스터 플래그와 무관하게 동작합니다.

`PREFERENCE_LEARNING`

M2 주기적 제안기(proposer) + 졸업 카드(graduation card) 흐름의 마스터 스위치. 0 이면 에이전트 루프가 사용자 메시지를 큐잉하지 않고, 제안기를 실행하지 않으며, 졸업 카드를 주입하지 않습니다. M1 의 PreferenceStore + REPL/CLI/REST 엔드포인트는 이 플래그가 꺼져 있어도 수동 관리를 위해 계속 사용할 수 있습니다.

형식: 0 / 1.
설정 위치: 설정 → 환경설정 (schema 키)

`PREFERENCE_PROPOSER_INTERVAL`

연속된 제안기 실행 사이의 턴 수. 제안기는 턴의 사용자 표시 응답이 전송된 후 fire-and-forget 비동기로 실행되므로, 이는 사용자 지연이 아니라 분산된 비용입니다. 낮을수록 학습 반응성이 높아지고 LLM 비용도 커집니다; 기본값 30 은 활발한 대화 기준 약 30분에 한 번꼴입니다.

형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_WEEKLY_QUOTA`

롤링 7일 윈도우 내에서 허용되는 최대 졸업 횟수. 한도에 도달하면 제안기가 해당 사이클을 건너뜁니다 — 새 후보는 큐에 쌓이지만 사용자에게 표시되지 않습니다. 수동 /preferences approve 는 이 할당량을 우회합니다(운영자 선택). AutoClaw 의 "주당 1~3회 심층 진화" 원칙을 반영합니다.

형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_DEDUP_THRESHOLD`

이 값을 초과하는 TF-IDF 코사인 점수를 가진 후보는 기존 라이브 선호(state ∈ {active, proposed, deprecated})의 중복으로 간주되어 저장 전에 폐기됩니다. 범위 [0, 1]; 0.85 는 공유 키워드가 있는 짧은 문장에서 오탐 없이 의역(paraphrase)을 잡아냅니다.

형식: [0, 1] 범위의 부동소수점.
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_PROPOSER_BATCH_SIZE`

단일 제안기 LLM 호출에 넣는 최대 최근 후보 수. 배치가 클수록 LLM 에 더 많은 클러스터링 신호를 주지만 토큰 비용이 커집니다; 기본값 200 은 나머지 컨텍스트를 고정하지 않으면서도 의미 있는 제안기 사이클을 돌리기에 충분합니다.

형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_MIN_CLUSTER_SIZE`

제안이 저장되기 전에 제안기의 LLM 이 단일 클러스터를 뒷받침한다고 보고해야 하는 최소 후보 메시지 수. 하한 3 은 단발성 관찰이 선호 노이즈를 부풀리는 것을 방지합니다.

형식: 양의 정수(≥ 2 강제).
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_ASK_COOLDOWN_HOURS`

동일한 선호에 대한 연속 졸업 요청 사이의 최소 시간. 사용자가 "나중에"라고 답하거나(또는 전혀 답하지 않으면) 해당 행은 proposed 로 유지되지만 이 윈도우가 지날 때까지 요청 큐에서 숨겨집니다. 기본값 24h 는 시나리오 흐름과 일치합니다.

형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_ASK_MIN_GAP_TURNS`

동일한 REPL 세션 내에서 (서로 다른 선호에 걸친) 연속 졸업 요청 사이의 최소 턴 수. 제안기 큐가 풍부하더라도 연달아 카드 요청이 나가는 것을 방지합니다.

형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_SKIP_IN_CHAT_ASK`

채팅 내 졸업 카드를 완전히 비활성화합니다. 1 이면 제안기는 여전히 실행되어 제안을 기록하지만, 카드는 시스템 프롬프트에 절대 주입되지 않습니다; 운영자는 REPL /preferences pending + approve 또는 CLI / REST 로 검토하고 승인합니다. 비대화형 배포에 유용합니다.

형식: 0 / 1.
설정 위치: 사용자 대상 설정 아님

M3: 키워드 스캐너 + 도구 수준 제약 시행

`PREFERENCE_STYLE_MIN_OBSERVATIONS`

스캐너가 자동 활성화하기 전에 필요한, 동일한 스타일 선호(dedup_key 기준)에 대한 독립적 관찰 횟수. 하한 1; 3+ 로 올리면 행이 고정되기 전에 사용자가 스스로를 번복할 기회가 더 많아집니다.

형식: 양의 정수. 기본값 2.
설정 위치: 사용자 대상 설정 아님

`PREFERENCE_HARD_UNDO_WINDOW_HOURS`

강신호 자동 활성화 이후 사용자가 여전히 /preferences undo <id> 로 되돌릴 수 있는 시간. 이 윈도우를 벗어난 행은 대신 /preferences deprecate <id> 로 폐기해야 합니다.

형식: 양의 정수. 기본값 24.
설정 위치: 사용자 대상 설정 아님

`MINARA_SKIP_FUND_CONFIRM`

자금 이동 확인 우회.

제어 대상: 통합 확인 게이트(ToolEntry 의 controlPolicy.confirm, tools/_security/tier-gate.ts 가 해석). 자금 이동 도구(swap / buy / sell / transfer / perps open-close-cancel / perp-wallet sweep+transfer / autopilot enable / workflow activate / strategy-studio start+deploy)는 미리 보기한 뒤, 사용자가 확인 카드(또는 다른 확인 증거)를 수락해야 실행합니다. 핸들러는 실행 전용입니다.
사용처: src/tools/_security/tier-gate.ts (confirmFlowHook), src/tools/_shared/confirm.ts (isFundConfirmBypassEnvSet) 경유.
설정 시점: 루프에 사람이 없고 호출자가 사람이 아닌 비대화형 컨텍스트에서만: - 백테스트 실행 - workflow 엔진 실행(서버 측 autopilot, DCA) - 자금 이동 경로를 의도적으로 건드리는 CI smoke 테스트 이 값을 설정하면 프로세스 전체(PROCESS-WIDE)에서 확인 게이트가 우회됩니다; 다른 탈출 경로는 없습니다. LLM 도, REPL 도 이를 뒤집을 수 없습니다.
미설정 시: 모든 자금 이동 호출이 확인 게이트를 거칩니다.
형식: 활성화하려면 1 / true / yes / on. 그 외에는 모두 off.
⚠ 모든 호출자가 사람이 아님을 확신하지 않는 한, 대화형 REPL 세션이나 프로덕션 배포에서는 절대 설정하지 마십시오.
설정 위치: 설정 → 환경설정 (schema 키)

`WORKBENCH_REMOTE_WEB_PTY_ENABLED`

원격 Gateway를 통해 대화형 워크벤치 Shell을 노출합니다.

제어 대상: Gateway가 루프백 이외 주소에 바인딩될 때 인증된 Web 클라이언트가 대화형 PTY 세션을 만들 수 있게 합니다.
사용처: apps/agent/src/gateway/api.ts 및 설정의 안전 환경설정 safety.remoteWebPty.
설정 시점: 신뢰할 수 있고 인증되며 지원되는 OS 샌드박스를 갖춘 호스트에서만 설정하세요. Web UI에서도 중요 위험을 명시적으로 확인한 뒤 활성화할 수 있습니다.
미설정 시: 원격 Web PTY는 비활성화 상태를 유지하며 루프백 Gateway는 기존 로컬 터미널 동작을 유지합니다.
형식: 1 / true / yes / on으로 활성화합니다. 워크스페이스 경계, 환경 변수 허용 목록, 소유권 검사, 동시 실행 상한, 프로세스 수명 제한은 계속 적용됩니다.
설정 위치: 설정 → 환경설정 (schema 키)

`WORKBENCH_REMOTE_SHELL_PROFILE_POLICY`

원격 워크벤치 터미널에서 사용자 Shell 설정을 불러오는 방식을 제어합니다.

제어 대상: 원격 터미널이 사용자 Shell rc 파일을 불러오기 전에 묻거나, 자동으로 불러오거나, 항상 Minara 기본 Shell 설정만 사용할지를 정합니다.
사용처: apps/agent/src/gateway/api.ts와 내부 워크벤치 터미널 capability 및 생성 라우트에서 사용합니다.
설정 시점: 사용자 rc 파일 실행이 예상되는 신뢰할 수 있는 원격 호스트에서만 user를 설정하세요. 불러오기를 금지하려면 builtin, 브라우저별로 명시한 탭 선택을 기억하게 하려면 prompt를 사용합니다.
미설정 시: 원격 Gateway의 기본값은 prompt입니다. 루프백 Gateway는 항상 사용자 Shell 설정을 불러오며 확인 창을 표시하지 않습니다.
형식: 값은 prompt, user, builtin 중 하나입니다. 잘못된 값은 prompt로 돌아가며 경고를 한 번 기록합니다.
설정 위치: 사용자 대상 설정 아님

`MINARA_DANGEROUSLY_SKIP_PERMISSIONS`

⚠ 위험 버튼 — 비자금(non-fund) 인가를 건너뛰는 마스터 스위치(Claude Code 의 --dangerously-skip-permissions 에 해당).

제어 대상: 비자금(NON-FUND) 대화형 인가 게이트를 한꺼번에 끄므로, 에이전트 실행이 이를 묻기 위해 멈추지 않습니다: 1. Tier 게이트 (tools/_security/tier-gate.ts) — terminal, write_file, execute_code 등에 대한 최초 사용 / 고위험 / 자율 부여 프롬프트. 2. Command-guard (tools/_security/command-guard.ts) — 셸 명령 트립와이어. 3. Sandbox write-escape 게이트 (tools/_security/sandbox-gate.ts). 4. Script-risk YELLOW 확인 (tools/_security/script-risk-gate.ts).
What it does NOT control: 자금 이동 확인 (tools/_shared/confirm.ts) — 이 값이 설정되어 있어도 swap / buy / sell / transfer / perps 는 여전히 confirm: true 가 필요합니다. 자금 이동은 MINARA_SKIP_FUND_CONFIRM 으로 독립적으로 게이트됩니다. web-ui 관점에서 이 스위치만 켠 것은 "Auto" 모드이며(동작은 자동 실행되지만 자금 이동은 여전히 확인), 둘 다 켜면 "Full auto" 입니다.
사용처: src/tools/_security/permission-skip.ts (isPermissionSkipSet), tier 게이트, command-guard, sandbox 게이트, script-risk 게이트에서 읽습니다.
설정하더라도 두 가지 안전 하한은 그대로 유지됩니다: - Script-risk RED 은 여전히 하드 거부입니다(RED 은 절대 프롬프트하지 않으므로 "인가" 표면이 아닙니다). - workflow 테스트 실행(ctx.test_run)은 여전히 절대 자금을 이동하지 않습니다.
설정 시점: 루프에 사람이 전혀 없고 모든 호출자를 신뢰하는 자동화 테스트 / 헤드리스 구동. 설정 방법은 세 가지입니다: - 이 환경 변수, 또는 - --dangerously-skip-permissions CLI 플래그, 또는 - ~/.minara/runtime-preferences.json 에 저장된 safety.skipPermissions 재정의(web UI 설정의 위험 구역에서도 minara settings unlock-critical 뒤에서 편집 가능).
미설정 시: 모든 게이트가 활성 상태이며 평소처럼 프롬프트 / 확인합니다.
형식: 활성화하려면 1 / true / yes / on. 그 외에는 모두 off.
⚠ 완전히 통제하지 못하는 대화형 REPL 이나 프로덕션 배포에서는 절대 설정하지 마십시오. LLM 은 이를 뒤집을 수 없습니다.
설정 위치: 설정 → 환경설정 (schema 키)

`MINARA_AUTO_REVIEW`

Smart 모드: 사용자에게 물을 비자금 승인을 리뷰 에이전트가 결정합니다(Codex AutoReview).

제어 대상: 비자금의 "원래 물었을" 지점을 InteractionQueue 대신 짧은 Guardian LLM 세션으로 보냅니다: 1. Tier 게이트 최초 사용 / 고위험 프롬프트(비자금). 2. 샌드박스 쓰기 탈출 및 명령 탈출 프롬프트. 3. Script-risk YELLOW 확인. 거부는 메인 에이전트로 돌아가는 도구 오류이며 확인 카드는 없습니다. 타임아웃 / 파싱 실패는 fail-closed(거부)입니다.
What it does NOT control: 자금 이동 확인은 계속 사람 경로입니다. Auto / Full (safety.skipPermissions)은 질문을 건너뛰며 Smart 보다 우선합니다. Coding 세션과 자동화는 Smart 를 사용하지 않습니다.
사용처: src/tools/_security/permission-skip.ts (isGuardianReviewEnabled) 및 src/guardian/.
설정 시점: 채팅 메뉴의 Smart / "대신 승인"을 프로세스 기본값으로 쓸 때 설정합니다. web UI 는 safety.autoReview 를 runtime-preferences.json 에도 저장합니다.
미설정 시: Ask 모드: 사용자가 비자금 작업을 확인합니다.
형식: 활성화하려면 1 / true / yes / on. 그 외에는 모두 off.
설정 위치: 설정 → 환경설정 (schema 키)

`DISABLE_SCRIPT_RISK_GATE`

⚠ 위험 버튼 — script-risk 킬 스위치.

제어 대상: execute_code(python/node 본문), terminal(셸 명령), write_file(최종 파일 내용), patch(적용 후 내용) 앞에서 실행되는 정적 분석 script-risk 게이트. 기본 동작은 본문을 RED(자동 거부), YELLOW(AskUserQuestion 확인), GREEN(허용) 으로 분류합니다. RED 은 대량 rm * / rm -r *, 워크스페이스 밖 경로 삭제, IMDS / SSRF, 컨테이너 탈출, 자격 증명 / 지갑 저장소 읽기, 간접 난독화 + 싱크 조합, 원격 pickle/yaml 역직렬화 등을 잡아냅니다. YELLOW 은 자금 이동 CLI 셸아웃(minara swap / cast send / forge --broadcast), 온체인 위험 호출(approve / Permit2 / Safe 소유자 변경), 환경 오염(NODE_OPTIONS / LD_PRELOAD / BASH_ENV), 특정 경로 rm, git / tarball / 비공식 인덱스로부터의 패키지 설치, heredoc 내장 스크립트, 프로세스 치환(process substitution) 을 잡아냅니다.
사용처: src/tools/_shared/script-risk-gate.ts.
설정 시점: AskUserQuestion 에 답할 사람이 없고 모든 호출자를 신뢰하는 사고 대응이나 완전 오프라인 CI 실행에서만 사용하십시오. 이것은 단일 boolean 이며 — RED 과 YELLOW 검사를 모두 우회합니다. 일상적인 workflow 예외에는 workflow 별 script_risk_policy 필드(workflow_activate 시점의 body_sha256 + 카테고리 사전 승인)를 사용하십시오; 단일 workflow 의 표면을 넓히려고 이 환경 변수를 설정하지 마십시오.
미설정 시: 게이트가 활성 상태입니다. RED 은 하드 거부하고, YELLOW 은 AskUserQuestion 으로 프롬프트합니다. 대화형 세션이 없는 cron / workflow 컨텍스트는 일치하는 script_risk_policy 가 없으면 script_risk_no_session 을 반환합니다.
형식: 활성화하려면 1 / true / yes / on. 그 외에는 모두 off.
Audit: 모든 게이트 결정은 script_risk_decisions SQLite 테이블에 기록됩니다 — 이 환경 변수를 설정하면 해당 행의 bypassed_by 열이 env_global 로 표시되어 운영자가 나중에 우회를 발견할 수 있습니다.
⚠ 모든 호출자가 사람이 아님을 확인하고 대량 삭제 / 자격 증명 유출 패턴이 프롬프트 없이 실행됨을 감수하지 않는 한, 대화형 REPL 세션이나 프로덕션 배포에서는 절대 설정하지 마십시오.
설정 위치: 설정 → 환경설정 (schema 키)

`DISABLE_OUTPUT_REDACTION`

⚠ 위험 버튼 — 출력 편집(output-redaction) 킬 스위치.

제어 대상: 하위 프로세스 출력에 대한 비밀 편집(redaction) 패스. execute_code / terminal 의 stdout+stderr(로컬 및 docker)는 모델 컨텍스트와 영속 채팅 이력에 들어가기 전에 자격 증명 형태의 문자열을 대상으로 세척됩니다: 어디에서든 벤더 토큰 형태(sk-…, ghp_…, xoxb-…, AKIA…, 전체 JWT), 그리고 비밀스러운 이름에 바인딩된 값(KEY=…, "api_key": "…", Authorization: 헤더, ://user:password@host URL). 일치 항목은 [REDACTED] 로 대체됩니다.
사용처: src/tools/_security/redact.ts(src/tools/_shared/subprocess-result.ts 및 docker 환경에서 적용).
설정 시점: 실제 자격 증명을 다루지 않는 세션에서 오탐(편집기가 훼손하는 정당한 출력)을 디버깅할 때만 사용하십시오. 이 스위치는 프로세스 시작 시 한 번만 읽힙니다 — terminal 도구 호출 내부의 export 로는 세션 도중에 뒤집을 수 없으며, 변경하려면 호스트 재시작이 필요합니다.
미설정 시: 모든 하위 프로세스 출력 경로에서 편집(redaction)이 활성 상태입니다.
형식: 비활성화하려면 1 / true / yes / on. 그 외에는 모두 on.
설정 위치: 사용자 대상 설정 아님

`MINARA_TOOL_RESULT_RETAIN_HOURS`

spill 파일 보존 윈도우.

제어 대상: <dataDir>/sandbox/files/.tool-results/ 아래에 영속된 초과 크기 도구 결과가 주기적 스윕(6시간마다)에 의해 삭제되기 전까지 몇 시간 동안 유지되는지. 동일한 값이 부팅 시 스윕과 장기 실행 스윕 모두를 구동하므로, 며칠간 켜져 있는 프로세스도 설정된 윈도우를 넘어 누적되지 않습니다.
사용처: src/core/tool-result-retain.ts, src/app.ts 의 sweepStaleSpillFiles 부팅 + 인터벌 호출에 연결됨.
설정 시점: - 24(기본값)는 일반적인 대화형 REPL 과 개발 작업에 적합한 값입니다 — LLM 이 이전 턴의 spill 을 read_file 할 충분한 시간을 줍니다. - 168(7일)은 유출된 도구 출력이 분기 검토나 규제 기관의 소급 조사까지 남아 있어야 하는 컴플라이언스 대상 배포에 적합한 감사 친화적 값입니다. - 1 은 일시적 CI 실행을 위한 공격적 정리 값입니다.
미설정 시: 24h.
형식: [1, 720] 범위의 양의 정수(1h ~ 30일). 형식이 잘못되었거나 범위를 벗어난 값은 경고와 함께 조용히 24h 로 폴백합니다.
설정 위치: 사용자 대상 설정 아님

──────────────────────────────────────────────────────────────────── 개인화 재빌드 — M3.2 이벤트 기반 임계값 ────────────────────────────────────────────────────────────────────

`CHAT_TURN_RECORDING`

(user_message, final_response, tool_calls) 의 턴별 기록을 chat_turns SQLite 테이블에 활성화합니다.

제어 대상: 에이전트 루프의 chatTurnRecorder 훅([src/core/agent-loop.ts] 에서 turn_complete 시 fire-and-forget). 이 기록은 개인화 메모리 추출 재구성기(memory-extraction rebuilder)의 입력입니다 — 이것이 없으면 rebuildMemories 는 스캔할 대상이 없어 no_turns 를 반환합니다.
사용처: src/app.ts isChatTurnRecordingEnabled() — 훅이 에이전트 루프에 등록되는지를 토글합니다.
설정 시점: 프로덕션에서는 기본 ON 으로 두십시오. 프라이버시에 민감한 배포이거나 개인화 계층과 분리하여 턴 루프를 디버깅할 때만 0 으로 설정하십시오.
미설정 시: 기본 ON — 모든 턴이 영속됩니다.
형식: 0 / false / no / off 는 비활성화합니다. 그 외의 값(빈 값 또는 미설정 포함)은 켜진 상태로 유지합니다.
설정 위치: 설정 → 환경설정 (schema 키)

`FIN_PROFILE_TRADING_SUMMARY_MIN_NEW_TRADES`

거래 요약 재구성기가 실행을 고려하기 전에 필요한 최소 신규 거래 수. 두 게이트 중 하나이며(다른 하나는 아래의 최소 확인 간격), 둘 다 충족되어야 합니다.

제어 대상: rebuildTradingSummary([src/memory/personalization-rebuilder.ts])의 tradingSummaryMinNewTrades 임계값. 스케줄러의 60분 안전망 틱에도 관여합니다 — 틱이 발생했지만 maxTradeId - last_seen < threshold 이면 재구성은 LLM 을 호출하지 않고 조용히 no-op 합니다.
사용처: 재구성기의 rebuildTradingSummary.
설정 시점: 작은 스왑을 많이 하여 요약이 너무 자주 갱신된다고 느끼는 사용자는 5+ 로 올리고, 거래가 있을 때마다 즉시 요약을 새로고침하려는 저volume 사용자는 1 로 낮추십시오.
미설정 시: 기본값 3 — 신규 거래 3건이 축적된 뒤에만 재구성합니다.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_TRADING_SUMMARY_MIN_INTERVAL_MIN`

성공한 두 거래 요약 재구성 사이의 최소 분(minute). 위의 신규 거래 임계값과 짝을 이룹니다.

제어 대상: tradingSummaryMinCheckIntervalMs. 기존 tradingSummaryCooldownMs 의미를 대체합니다.
사용처: rebuildTradingSummary 게이트 1.
설정 시점: 요약을 빠르게 수렴시키려는 파워 유저는 낮추고(10~~15), LLM 비용을 줄이려면 올리십시오(60~~120).
미설정 시: 기본값 30분.
형식: 양의 정수(분 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_TRADING_SUMMARY_MAX_TRADES`

FULL 재생성 모드(콜드 스타트 또는 force=true)에서 재구성당 고려되는 최대 거래 수.

제어 대상: 이전 요약이 없을 때 LLM 에 전달되는 거래 수의 상한. 증분 병합은 아래의 별도 INCREMENTAL_MAX_TRADES 윈도우를 사용합니다.
사용처: rebuildTradingSummary 의 full-regen 경로.
미설정 시: 기본값 100.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_TRADING_SUMMARY_INCREMENTAL_MAX_TRADES`

증분 병합 모드(이전 요약이 존재할 때) LLM 에 공급되는 최대 신규 거래 수. 각 재구성을 저렴하게 유지하기 위해 작게 유지합니다.

제어 대상: tradingSummaryIncrementalMaxTrades. LLM 은 (existingSummary, newTrades) 를 보고 이를 병합합니다.
미설정 시: 기본값 50.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_TRADING_SUMMARY_MAX_INCREMENTAL_RUNS`

재구성기가 전체 재생성을 강제하기 전에 실행될 수 있는 연속 증분 병합 횟수. 증분 모드는 신규 거래 델타만으로 자체 이전 요약을 다시 쓰므로, 작은 오류와 유령 "장기 패턴"이 여러 병합에 걸쳐 누적됩니다; 주기적 전체 재생성은 실제 거래 이력을 다시 읽어 요약을 재정렬합니다.

제어 대상: tradingSummaryMaxIncrementalRuns. 사용자별 카운터(financial_profile.trading_summary_incremental_runs)는 증분 병합마다 증가하고 전체 재생성 시 0 으로 초기화됩니다; 이 상한에 도달하면 다음 재구성은 전체 재생성이 됩니다.
미설정 시: 기본값 10.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_MEMORIES_MIN_NEW_TURNS`

rebuildMemories 가 스캔하기 전에 필요한 최소 신규 채팅 턴 수. 거래 요약의 신규 거래 임계값과 유사합니다.

제어 대상: memoriesMinNewTurns. 메모리 추출 재구성기의 두 번째 게이트(최소 확인 간격과 함께).
사용처: rebuildMemories 게이트 2.
설정 시점: 사실을 빠르게 생성하는 수다스러운 사용자는 낮추고(2~3), 느린 단일 질문 대화는 올리십시오(10+).
미설정 시: 기본값 5.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_MEMORIES_MIN_INTERVAL_MIN`

성공한 두 메모리 추출 재구성 사이의 최소 분(minute).

제어 대상: memoriesMinCheckIntervalMs.
미설정 시: 기본값 10분.
형식: 양의 정수(분 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_EVENT_DEBOUNCE_SEC`

이벤트 기반 scheduleCheck(dim) 호출의 디바운스 윈도우. 빠른 데이터 쓰기 이벤트 버스트(예: 500ms 내 5건의 거래)를 윈도우 경과 후 단일 게이트 검사 재구성 시도로 합칩니다.

제어 대상: eventDebounceMs. 재구성기는 차원(dimension)별로 동일한 setTimeout 을 재사용하며; 윈도우 내에 새 이벤트가 발생하면 타이머를 초기화합니다.
사용처: PersonalizationRebuilder.scheduleCheck.
설정 시점: 많은 시뮬레이션 거래가 연달아 들어오는 백테스트 / CI 시나리오에서는 60+ 로 올리고, 디버깅 중 거의 즉각적인 재구성 피드백을 원하는 개발자는 5~10 으로 낮추십시오.
미설정 시: 기본값 30초.
형식: 양의 정수(초 단위).
설정 위치: 사용자 대상 설정 아님

오프-에이전트 히스토리 미러

개인화 재빌더는 이제 세 가지 소스를 소비합니다: 로컬 trade_history (세션 내 에이전트), perps_fills(Minara 의 /v1/perp-wallets/fills 크로스-서브 미러), external_spot_activities(Minara 의 /v1/tx/cross-chain/activities). 아래 노브는 미러가 스스로 얼마나 최신 상태를 유지하는지, 그리고 LLM 재빌더가 그중 얼마를 읽는지를 튜닝합니다.

`FIN_PROFILE_HISTORY_SYNC_WINDOW_DAYS`

일 단위 롤링 동기화 윈도우.

제어 대상: perps 체결과 spot 활동 모두의 컷오프. now - WINDOW_DAYS 보다 오래된 것은 절대 가져오지 않습니다.
사용처: MinaraHistorySync 및 tradingSummaryAggregateWindowDays 를 통한 거래 요약 집계 쿼리.
설정 시점: 장기 스타일 포착을 원하는 트레이더는 늘리고, 미러가 수만 행으로 커질 수 있는 고빈도 사용자는 줄이십시오.
미설정 시: 기본값 90일.
형식: 양의 정수(일 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_MIN_INTERVAL_MIN`

연속된 동기화 트리거 사이의 스로틀 하한. 윈도우 내의 여러 scheduleSync() 호출은 결국 단일 실행으로 합쳐집니다. 모든 거래 이벤트가 업스트림 API 호출로 이어지는 것을 방지합니다.

사용처: MinaraHistorySync.scheduleSync + runIfStale.
미설정 시: 기본값 5분.
형식: 양의 정수(분 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_TIMEOUT_SEC`

단일 syncAll() 호출의 하드 타임아웃. AbortController 를 통해 라우팅되어 기저 HTTP 호출이 고아가 되지 않고 취소됩니다.

미설정 시: 기본값 8초.
형식: 양의 정수(초 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_PAGE_HINT`

페이지네이션 파라미터가 없는 perps 체결 엔드포인트에 대한 "이 페이지는 아마 가득 찼다"는 업스트림 휴리스틱. getPerpSubAccountFills 가 이 개수 이상의 행을 반환하면 같은 윈도우에 더 있을 수 있다고 가정하고 startTime 을 앞으로 밀어 다시 요청합니다.

미설정 시: 기본값 500.
형식: 양의 정수(행 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_OVERLAP_SEC`

아마도 잘린(truncated) 페이지에서 startTime 을 앞으로 밀 때의 중첩(초). 중첩이 클수록 낭비되는 페치가 많고, 작을수록 경계에서 체결을 건너뛸 위험이 높습니다. fill_uid 중복 제거가 이중 계산을 무해하게 만듭니다.

미설정 시: 기본값 60초.
형식: 양의 정수(초 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_MAX_ROUNDS_PER_SUB`

서브 계정당 절단-롤링 루프의 하드 상한. 이 라운드 수 이후에는 중단하고, 다음 동기화가 워터마크에서 이어가도록 합니다.

미설정 시: 기본값 10.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_MAX_FAILURES`

(source, sub_account_id) 별 연속 실패 임계값. 이 횟수 이상이면 동기화는 정상 스케줄링 중 해당 키를 건너뜁니다; 워터마크는 그대로 유지되어 다음 시도가 같은 지점에서 재개됩니다. 이 건너뜀은 영구적이지 않습니다 — _FAILURE_COOLDOWN_MIN 참조.

미설정 시: 기본값 5.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_FAILURE_COOLDOWN_MIN`

키가 MAX_FAILURES 에 도달한 뒤, 다음 프로브 시도는 last_synced_at 이후 이 쿨다운이 경과해야 게이트가 열립니다. 프로브 성공 → 카운터가 0 으로 초기화; 프로브 실패 → 카운터가 계속 증가. 일시적 장애가 미러를 영구적으로 비활성화하는 것을 방지합니다.

미설정 시: 기본값 30분.
형식: 양의 정수(분 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_SPOT_MAX_PAGES`

spot 페이지네이션 루프의 하드 상한. 업스트림이 계속 page-full 응답을 반환할 때 폭주하는 페이지네이션을 멈춥니다.

미설정 시: 기본값 20.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_HISTORY_SYNC_SPOT_PAGE_SIZE`

spot 페이지네이션 배치 크기. Minara 에 limit 으로 전달됩니다. 업스트림 API 가 지원해야 하며; 100 이 문서화된 기본값입니다.

미설정 시: 기본값 100.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_TRADING_SUMMARY_PERPS_RECENT_FILLS`

가장 최근 perps 체결 중 몇 건을 LLM 재구성에 보낼지. 심볼별 집계는 항상 전부 전송되며; 이 knob 은 원시 체결 로그만 제한합니다.

미설정 시: 기본값 30.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_TRADING_SUMMARY_SPOT_RECENT_ACTIVITIES`

spot 에 대해 동일.

미설정 시: 기본값 20.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_TRADING_SUMMARY_AGGREGATE_WINDOW_DAYS`

LLM 재구성에 공급되는 심볼별 / 페어별 집계의 윈도우. 보통 HISTORY_SYNC_WINDOW_DAYS 와 같으며; 최근 행동에 집중하려면 더 작게 할 수 있습니다.

미설정 시: 기본값 90.
형식: 양의 정수(일 단위).
설정 위치: 사용자 대상 설정 아님

`FIN_PROFILE_MEMORY_SOFT_DELETE_RETENTION_DAYS`

소프트 삭제된 메모리가 30분 정리 cron 이 물리적으로 제거하기 전까지 복구 가능한 기간. 웹 UI 의 "삭제 취소" 토스트는 5초 내에 복원하며; 이 knob 은 행을 남겨 두어 CLI 수준 복원이 여전히 되살릴 수 있게 함으로써 장기적인 실수 삭제를 방지합니다.

미설정 시: 기본값 30일.
형식: 양의 정수(일 단위).
설정 위치: 사용자 대상 설정 아님

`MINARA_HL_DEX_DISCOVERY`

perps 포지션, 주문, 이력을 동기화할 때 실시간 Hyperliquid perpDexs 디스커버리에 옵트인합니다.

제어 대상: perps 스냅샷과 이력 동기화를 위한 스윕당 dex 팬아웃. 기본값은 현재 사용자 코호트가 포지션을 보유한 것으로 알려진 두 개의 dex 만 조회합니다("" 기본값 + "xyz" 주식/원자재) — 스윕당 16개의 HL 요청으로, HL 의 IP 당 rate limit 내에 충분히 들어갑니다. 이 플래그가 켜지면 스냅샷은 HL perpDexs(10분 캐시)도 호출하여 반환되는 모든 명명된 dex(xyz, flx, vntl, hyna, km, abcd, cash, para, ...)에 걸쳐 팬아웃합니다. 일반적인 4-sub 사용자의 경우 스윕당 예산이 약 72개 요청으로 늘어나 공개 /info 엔드포인트가 안정적으로 429 를 반환합니다.
설정 시점: "" / "xyz" 쌍 밖의 명명된 dex(예: flx, vntl)에 실제로 포지션을 보유한 경우에만 켜십시오. 대부분의 사용자는 꺼 두어야 합니다.
미설정 시: 검증된 ["", "xyz"] 쌍만 조회되며, 서브별 clearinghouseState + frontendOpenOrders 팬아웃이 HL 의 rate-limit 예산 내에 유지됩니다.
형식: 활성화하려면 1 / true / yes / on; 그 외(또는 미설정)에는 디스커버리를 비활성화 상태로 둡니다.
설정 위치: 설정 → 환경설정 (schema 키)

`WORKFLOW_HEARTBEAT_CHECK_MS`

workflow heartbeat 모니터 스윕 주기. 제어 대상: HeartbeatMonitor.checkIntervalMs([src/workflow/heartbeat.ts]). 마지막 스텝 updateInstance 가 MAX_SILENCE_MS 보다 오래된 실행 인스턴스는 status="canceled" cancel_reason="timeout" 로 표시됩니다.

설정 시점: 행이 걸리는 것을 빠르게 드러내려면 dev/staging 에서 더 짧게(예: 5000), SQLite 스캔 부하를 줄이려면 프로덕션에서 더 길게 설정하십시오.
미설정 시: 기본값 30 000 ms(30초).
형식: 양의 정수(밀리초). 숫자가 아니거나 양수가 아닌 값은 기본값으로 폴백합니다.
설정 위치: 사용자 대상 설정 아님

`WORKFLOW_HEARTBEAT_MAX_SILENCE_MS`

실행 중인 workflow 가 타임아웃된 것으로 간주되기 전까지의 침묵 임계값.

제어 대상: HeartbeatMonitor.maxSilenceMs. last_heartbeat_ms 가 매 commitStepAdvance 마다 갱신되므로, 허용 가능한 단일 스텝의 최대 지속 시간도 제한합니다.
설정 시점: 긴 agent_turn 스텝이나 외부 API 페치가 있는 workflow 는 기본값 300 000 ms 이상으로 올리십시오.
미설정 시: 기본값 300 000 ms(5분).
형식: 양의 정수(밀리초).
설정 위치: 사용자 대상 설정 아님

`WORKFLOW_MAX_QUEUE_DEPTH`

정의별 cron/event 실행 큐 상한([src/workflow/triggers.ts]). 각 workflow 정의는 자체 FIFO 를 가지며; 큐가 가득 차면 가장 오래된(OLDEST) 대기 실행을 버립니다.

설정 시점: 트리거가 단일 실행 시간을 정당하게 앞지를 수 있고 catch-up 이 중요한 workflow 는 올리고; 가장 최신 신호만 중요하면 1 로 낮추십시오.
미설정 시: 기본값 10.
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`MINARA_SS_CODEGEN_MAX_ITER`

오프라인 strategy-codegen 서브에이전트가 벤치마크 실행당 허용받는 "코드 생성 → 임시(ephemeral) 백테스트 → 개선" 반복 횟수.

제어 대상: runStrategyCodeSubagent([src/core/strategy-code-subagent.ts])에 있는 codegen 루프의 스텝 예산. 서브에이전트는 이 스텝 수만큼 실행됩니다. 모델이 그 예산 내에서 언제 백테스트하고 언제 멈출지 결정하며; 반환 시 성공 여부는 최종 백테스트로부터 재계산됩니다(status COMPLETED + 0이 아닌 거래 + drawdown < 0.95).
사용처: src/core/strategy-code-subagent.ts 의 runStrategyCodeSubagent, strategy-rl 벤치마크 러너가 구동합니다(오프라인 튜닝 전용; 채팅 대면 도구 아님).
미설정 시 기본값: 3
클램프 범위: [1, 10]
형식: 양의 정수
운영자는 llmClient 가 빠르고 저렴하며(예: Haiku) 더 나은 수렴을 원할 때 이 값을 올리고; 느리거나 비싼 모델을 사용하며 더 낮은 품질의 코드를 감수할 때는 낮춥니다(1–2).
설정 위치: 사용자 대상 설정 아님

`MINARA_STRATEGY_SKILL_RL_ENABLED`

Strategy Studio Skill RL / 자가 진화 Skill 텍스트에 대한 옵트인 파일럿.

제어 대상: 저장소 기반 Strategy Studio skill 버전, 사용자별 전략 선호 오버레이, 롤아웃 추적, 오프라인 codegen 벤치마크 루프를 위한 보상 로깅.
미설정 시 기본값: 비활성화됨. 비활성화되면 bootstrap 은 strategy_skill_* 테이블을 생성하지 않으며 프로덕션 Strategy Studio skill 프롬프트나 codegen 정책을 변경하지 않습니다.
허용되는 참값: 1 | true | yes | on
Scope: 이 파일럿에서는 Strategy Studio 에만 해당하며; 모든 skill 을 위한 전역 RL 하네스가 아닙니다.
설정 위치: 설정 → 환경설정 (schema 키)

`MINARA_STRATEGY_CONTEXT_RL_ENABLED`

Strategy Studio Context Policy RL 옵트인 파일럿.

제어 대상: 버전 관리되는 외부 컨텍스트 선택 정책, 정책 인식 컨텍스트 수집, three-arm replay 벤치마크, 명시적 승격 / 롤백 감사 기록.
미설정 시 기본값: 비활성화됨. MINARA_STRATEGY_SKILL_RL_ENABLED=1 이 필요합니다. 비활성화되면 bootstrap 은 strategy_context_policy_* 테이블을 생성하지 않으며 외부 컨텍스트 공급자는 변경되지 않습니다.
허용되는 참값: 1 | true | yes | on
Scope: Strategy Studio 외부 컨텍스트 선택에만 해당.
설정 위치: 설정 → 환경설정 (schema 키)

`MINARA_SKILL_ROUTER_RL_ENABLED`

Skill Router 정책 진화를 위한 일반 Agent Harness RL 옵트인 파일럿.

제어 대상: 버전 관리되는 skill 순위 정책, 오프라인 라우팅 벤치마크 케이스, 제한된 정책 탐색, 명시적 승격 / 롤백, 턴별 Skill 카탈로그의 승격된 정책 순서 지정.
미설정 시 기본값: 비활성화됨. Bootstrap 은 skill_router_* 테이블을 생성하지 않고, Skill 카탈로그는 기존 우선순위를 유지하며, 내장 did-you-mean 라우팅 동작은 변경되지 않습니다.
허용되는 참값: 1 | true | yes | on
Scope: 일반 Skill 디스커버리/라우팅에만 해당. Skill 텍스트, 도구 권한 tier, 안전 게이트, 모델 가중치는 절대 변경하지 않습니다.
설정 위치: 설정 → 환경설정 (schema 키)

───────────────────────────────────────────────────────────────── Institution Mode (멀티 에이전트 회사 시뮬레이션) ───────────────────────────────────────────────────────────────── minara_institution_analyze 도구는 고위험 단일 자산 분석을 위해 6단계 파이프라인(4명의 애널리스트 병렬 → 불/베어 리서치 토론 → 리서치 매니저 → 트레이더 → 3자 리스크 토론 → 포트폴리오 매니저)을 소집합니다. TradingAgents (https://github.com/TauricResearch/TradingAgents) 를 본떴습니다. 라운드 수의 기본값은 TradingAgents 의 default_config.py 에 맞춰져 있습니다. 타임아웃 / 토큰 상한은 Minara 관행(deep-research 단계 예산, 에이전트 루프 max_tokens)을 따릅니다. 아래 모든 변수는 에이전트 루프 인프라이며, 프로젝트의 env-var 명명 규칙에 따라 MINARA_ 접두사가 없습니다.

`INSTITUTION_MAX_DEBATE_ROUNDS`

bull vs bear 교대 라운드.

제어 대상: institution 파이프라인 Phase 2 의 전체 라운드 수. 1 라운드 = 총 2턴(bull 1회, bear 1회). 높을수록 → 논쟁이 풍부해지고 LLM 비용이 커집니다.
사용처: src/tools/institution/orchestrator.ts 의 runInstitution
Surfaced via tool: minara_institution_analyze(max_debate_rounds 인자가 한 호출에 대해 이를 재정의)
미설정 시 기본값: 1 (TradingAgents max_debate_rounds: 1 과 일치)
클램프 범위: [1, 5]
형식: 양의 정수
설정 시점: bull 과 bear 가 두 번 맞붙기를 원하는 고확신 거래에는 2 로 올리고; 일상적인 분석은 비용을 억제하기 위해 1 로 두십시오.
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_MAX_RISK_ROUNDS`

aggressive/conservative/neutral 순환(rotation) 라운드.

제어 대상: Phase 5 의 전체 라운드 수. 1 라운드 = 총 3턴(Aggressive → Conservative → Neutral). 높을수록 → 더 철저한 리스크 검토, 더 많은 LLM 비용.
사용처: src/tools/institution/orchestrator.ts 의 runInstitution
Surfaced via tool: minara_institution_analyze(max_risk_rounds 인자가 한 호출에 대해 이를 재정의)
미설정 시 기본값: 1 (TradingAgents max_risk_discuss_rounds: 1 과 일치)
클램프 범위: [1, 5]
형식: 양의 정수
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_WALL_CLOCK_TIMEOUT_MS`

단일 institution 실행의 전역 wall-clock 예산.

제어 대상: 단일 minara_institution_analyze 호출의 총 경과 시간에 대한 하드 상한. 초과하면 오케스트레이터가 진행 중인 단계를 단락시키고 완료된 것과 meta.truncated: true 를 반환합니다. 개별 하위 LLM 호출의 호출당 타임아웃은 INSTITUTION_PER_CALL_TIMEOUT_MS(아래 참조)가 관장하며 이 wall clock 을 절대 초과하지 않도록 클램프됩니다.
사용처: src/tools/institution/orchestrator.ts 의 runInstitution
미설정 시 기본값: 1200000 (20분 — 순차적인 5분 호출 두 번과 나머지 파이프라인에 충분한 여유를 줌)
클램프 범위: [60000, 1800000]
형식: 정수 밀리초
설정 시점: 부분 결과를 감수하는 더 저렴하고 빠른 실행에는 낮추고(예: 600000 = 10분); deep 모델로 대규모 논쟁을 실행할 때는 올리십시오(예: 1800000 = 30분).
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_PER_CALL_TIMEOUT_MS`

institution 파이프라인 내부의 LLM 호출당 타임아웃.

제어 대상: 모든 하위 LLM 호출(분석가, 토론자, 매니저, 구조화 출력 재시도)에 적용되는 호출당 중단 신호. 데이터 도구를 2~3개 호출하고 단일 서브에이전트 루프에서 구조화된 AnalystReport 를 작성해야 하는 분석가는 빡빡한 상한보다 더 오래 걸리기 일쑤입니다 — 이전의 60초 기본값(wallClock/10)은 작성 도중에 이들을 중단시켰습니다. 새 300초 기본값은 멈춘 공급자를 여전히 방어하면서 그 작업에 충분한 예산을 남깁니다.
사용처: src/tools/institution/orchestrator.ts 의 perCallTimeoutMs(runInstitutionSubagent 로도 이어짐)
미설정 시 기본값: 300000 (5분)
클램프 범위: [5000, INSTITUTION_WALL_CLOCK_TIMEOUT_MS]
형식: 정수 밀리초
설정 시점: 빠른 quick-model 에서 실행하며 분석가가 wall clock 을 소모하기보다 빠르게 실패하기를 원할 때는 낮추고(예: 60000 = 1분); 공급자 응답이 느리면 wall clock 을 함께 올릴 때만 올리십시오(예: 600000).
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_MAX_OUTPUT_TOKENS_PER_TURN`

LLM 호출당 출력 상한.

제어 대상: institution 파이프라인 내부의 모든 LLM 호출(분석가, 토론자, 매니저, 구조화 출력 재시도)에 일률적으로 적용되는 max_tokens 상한. 행동 knob 이 아니라 비용 상한으로 작동합니다 — 각 역할의 프롬프트가 어차피 간결한 출력을 요구하므로, 이것은 폭주하는 생성만 방어합니다.
사용처: src/tools/institution/ 의 runInstitution 및 runInstitutionSubagent
미설정 시 기본값: 4096 (에이전트 루프의 기본 max_tokens 와 일치)
클램프 범위: [1024, 16384]
형식: 양의 정수
설정 시점: 실험 중 비용 통제를 위해 낮추고; PM 이 executive_summary 를 계속 잘라먹으면 올리십시오.
설정 위치: 사용자 대상 설정 아님

───────────────────────────────────────────────────────────────── Institution Mode v2 — 자가 학습 (PR 1 + PR 2) ───────────────────────────────────────────────────────────────── 지속성 + Phase B 리플렉션 래더 + Phase 0 회고 리프레시. 런타임 데이터는 Minara 의 나머지와 동일한 SQLite db 에 유지됩니다. 리플렉션 alpha 수치는 PR 4 의 방법론 졸업 피드백 루프에 공급됩니다 (후속 작업에서 안착).

`INSTITUTION_LEARNING_ENABLED`

v2 자가 학습 경로의 마스터 스위치(institution_runs / institution_role_outputs / institution_reflections 영속화).

제어 대상: 켜지면 모든 minara_institution_analyze 실행이 전체 구조화 아티팩트(PM 평점 + 논지 + 역할별 출력 + 방법론 참조)를 fire-and-forget 로 영속화합니다. 꺼지면 캡처 훅이 no-op 하고 institution_* 테이블이 비어 있게 됩니다.
사용처: src/learning/institution/capture-hook.ts 의 captureInstitutionRun
미설정 시 기본값: on
형식: on | off | 1/true/yes — 그 외(미설정 포함)에는 모두 → on
설정 시점: institution 행을 디스크에 전혀 쓰고 싶지 않은 일시적 / CI / dev 실행에서만 off 로 설정하십시오. 프로덕션은 켜 두며; 영속된 행은 다운스트림의 Phase B reflection + 방법론 졸업에 공급됩니다.
설정 위치: 설정 → 환경설정 (schema 키)

`INSTITUTION_RETROSPECT_ENABLED`

Phase 0 지연 새로고침(lazy refresh) 마스터 스위치.

제어 대상: 켜지면 모든 새 minara_institution_analyze 호출이 동일한 (ticker, asset_class) 의 최근 실행들을 훑어, 최신 reflection 이 오래된 것에 대해 lazy_refresh reflection 을 씁니다. 운영자는 /institution-history 로 확인할 수 있습니다.
사용처: src/tools/institution/index.ts 의 runSingleTicker(Phase 0 블록), src/learning/institution/reflect.ts 의 runLazyRefresh
미설정 시 기본값: on
형식: on | off
설정 시점: YahooFinance 네트워크 호출이 가치 없이 실행을 느리게 하는 CI / 배치 테스트에서는 끄십시오. 표준 cron reflection(스케줄된 경우)은 독립적으로 계속 실행됩니다.
설정 위치: 설정 → 환경설정 (schema 키)

`INSTITUTION_RETROSPECT_LIMIT`

Phase 0 이력 깊이.

제어 대상: Phase 0 이 어떤 것을 lazy-refresh 할지 결정하기 전에 (ticker, asset_class) 당 가져올 이전 실행의 최대 개수.
사용처: src/tools/institution/index.ts 의 runSingleTicker
미설정 시 기본값: 10
클램프 범위: [1, 50]
형식: 양의 정수
설정 시점: 호출당 지연을 제한하려는 수다스러운 멀티 티커 사용자는 낮추고(3~5); 작은 티커 집합에서 최신성보다 회고적 컨텍스트가 더 가치 있을 때는 올리십시오(20+).
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_RETROSPECT_TIMEOUT_MS`

Phase 0 wall clock.

제어 대상: institution 호출당 Phase 0 이 lazy-refresh 쓰기에 소비하는 총 시간의 하드 상한. 유효 타임아웃은 min(this var, INSTITUTION_WALL_CLOCK_TIMEOUT_MS / 2) 이며 하한 5초 — Phase 1 이 시작될 때 오케스트레이터(Phase 1-6)가 선언된 wall-clock 예산의 최소 50% 를 갖도록 보장합니다. 이 상한이 없으면 60초 도구 호출 예산이 결국 총 180초 이상 걸릴 수 있습니다(codex review round 2).
사용처: src/tools/institution/index.ts 의 runSingleTicker
미설정 시 기본값: 120000 (2분)
클램프 범위: [5000, INSTITUTION_WALL_CLOCK_TIMEOUT_MS / 2]
형식: 양의 정수 밀리초
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_LAZY_REFRESH_STALE_HOURS`

Phase 0 staleness 임계값.

제어 대상: 이전 실행의 가장 최근 reflection 은 evaluated_at 이 이 시간(시간 단위)보다 오래되면 "오래된(stale)" 것(그리고 lazy-refresh 대상)으로 간주됩니다. 값이 작을수록 호출당 더 많은 새로고침을 씁니다(= 비용 증가 + 더 최신의 PM 컨텍스트); 값이 클수록 일일 cron 에 의존해 최신 상태를 유지합니다.
사용처: src/learning/institution/reflect.ts 의 shouldWriteLazyRefresh
미설정 시 기본값: 24
클램프 범위: [1, 168]
형식: 양의 정수(시간 단위)
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_LAZY_REFRESH_DEDUPE_HOURS`

Phase 0 쓰기 중복 제거.

제어 대상: 동일한 실행에 대한 연속 lazy_refresh 쓰기 사이의 최소 시간(시간 단위). /institution BTC 를 10분 내에 세 번 호출해도 거의 동일한 reflection 을 세 개 생성하지 않도록 방지합니다 — 두 번째 + 세 번째 호출은 첫 번째 행을 재사용합니다.
사용처: src/learning/institution/reflect.ts 의 shouldWriteLazyRefresh
미설정 시 기본값: 6
클램프 범위: [1, 48]
형식: 양의 정수(시간 단위)
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_AUTO_STALE_DAYS`

자동 stale 승격 임계값.

제어 대상: open institution 실행은 최종 확정(finalize) 없이 나이가 이 일수를 초과하면 auto_stale 로 승격됩니다. auto-stale 실행은 계속 Phase B reflection 을 받지만 PM past_context 주입에서 가중치가 낮아집니다(PR 2 다운스트림 연결).
사용처: src/learning/institution/reflect.ts 의 runScheduledReflections
미설정 시 기본값: 90
클램프 범위: [30, 365]
형식: 양의 정수(일 단위)
설정 위치: 사용자 대상 설정 아님

`INSTITUTION_BENCHMARK_CRYPTO` / `INSTITUTION_BENCHMARK_STOCK` / `INSTITUTION_BENCHMARK_FOREX`

자산 클래스별 alpha 벤치마크. Phase B reflection alpha 는 동일 윈도우에 대해 raw_return - benchmark_return 으로 계산됩니다. 구성된 가격 소스가 해석할 수 있는 티커로 설정하십시오(기본 Yahoo).

Defaults when unset: crypto → BTC stock → SPY forex → DXY
(commodity / stablecoin / unknown 은 의도적으로 벤치마크가 없으며
— 해당 클래스의 alpha 는 null 로 기록됩니다.)
형식: 티커 문자열
설정 위치: 사용자 대상 설정 아님

애널리스트 복구

각 Phase-1 애널리스트 슬롯은 모델을 자유 도구 호출 루프로 실행한 뒤, HEADLINE / KEY FINDINGS / CONFIDENCE 형식의 구조화된 산문 요약을 요청하는 단일 종합 턴을 실행합니다. 오케스트레이터는 그 산문을 직접 AnalystReport 로 파싱합니다 — 강제 제출 toolChoice 단계도, 재시도 하네스도 없습니다. 종합 결과가 비어 있거나 파싱 불가하면, 오케스트레이터는 항상 사용 가능한 리포트를 내보내는 buildSubagentSummaryReport 로 폴백합니다(도구가 성공했을 때는 원시 도구 출력에서, 그렇지 않을 때는 역할 기본 추론으로). 다운스트림 단계는 항상 사용 가능한 요약을 받으며, 기존 data_gap 플래그는 폐기되었습니다. 운영자가 튜닝할 수 있는 env 변수는 없습니다 — 계약은 "항상 사용 가능한 무언가를 만든다"이며 튜닝할 예산이 없습니다.

`INSTITUTION_FORCE_RESOLVER_PREFLIGHT`

상시 켜짐 canonical preflight.

제어 대상: 기본적으로 서버 측 canonical-identity preflight 는 classifyAsset(ticker) === "unknown" 일 때만 실행됩니다. 이를 true 로 설정하면 모든 티커에 대해 preflight 를 강제하는데, 이는 ops 검증(resolver 가 잘 알려진 티커에서도 올바르게 동작하는가?)에 유용합니다. 약간의 지연 비용이 있습니다(캐시 히트 ~50ms, 캐시 미스 ~200-500ms).
사용처: 오케스트레이터 preflight 단계.
미설정 시 기본값: false
허용 값: true / false / 1 / 0
설정 위치: 사용자 대상 설정 아님

Canonical Asset 캐시

canonical-asset 리졸버는 SQLite 캐시를 통해 write-through 하므로, 에이전트가 티커를 두 번째로 볼 때는 CoinGecko / CMC / DexScreener 를 다시 히트하지 않습니다. TTL 은 결과별입니다 — 고유한 해석은 모호한 것보다 더 오래 캐시될 수 있고, 빈 결과는 빠르게 만료되어 제공자가 더 많은 데이터를 게시한 후 다시 시도합니다.

`CANONICAL_ASSET_CACHE_TTL_RESOLVED_DAYS`

outcome: "resolved"(단일 canonical chain+contract 또는 native+chain)의 TTL.

사용처: src/learning/canonical-asset-cache.ts
미설정 시 기본값: 30
형식: 양의 정수(일 단위)
설정 위치: 사용자 대상 설정 아님

`CANONICAL_ASSET_CACHE_TTL_MULTI_DAYS`

outcome: "multi"(멀티 체인 배포, 예: 20개 체인의 USDC)의 TTL. 운영자/사용자 명확화가 특정 체인에 고정될 수 있으므로 resolved 보다 짧습니다.

사용처: src/learning/canonical-asset-cache.ts
미설정 시 기본값: 14
형식: 양의 정수(일 단위)
설정 위치: 사용자 대상 설정 아님

`CANONICAL_ASSET_CACHE_TTL_AMBIGUOUS_DAYS`

outcome: "ambiguous"(공급자 결과가 불일치, 다수의 토큰 후보)의 TTL. 공급자 데이터가 수렴하거나 사용자 재정의가 고정된 뒤 다시 해석하도록 짧게 설정합니다.

사용처: src/learning/canonical-asset-cache.ts
미설정 시 기본값: 7
형식: 양의 정수(일 단위)
설정 위치: 사용자 대상 설정 아님

`CANONICAL_ASSET_CACHE_TTL_NONE_DAYS`

outcome: "none"(어떤 소스도 데이터를 반환하지 않음)의 TTL. 매우 짧음 — 공급자가 매일 업데이트하므로, 부정 결과를 캐싱하기보다 곧 새로 시도하기를 원합니다.

사용처: src/learning/canonical-asset-cache.ts
미설정 시 기본값: 1
형식: 양의 정수(일 단위)
설정 위치: 사용자 대상 설정 아님

`CANONICAL_ASSET_CACHE_TTL_USER_DAYS`

사용자 제공 항목(minara assets pin 또는 배너 CTA 를 통한 운영자 재정의)의 TTL. 사용자가 원하는 canonical 을 명시적으로 알려주었으므로 길게 설정합니다; pin 항목은 공급자 해석을 대체합니다.

사용처: src/learning/canonical-asset-cache.ts
미설정 시 기본값: 365
형식: 양의 정수(일 단위)
설정 위치: 사용자 대상 설정 아님

`CANONICAL_ASSET_CACHE_FALLBACK_TO_EXPIRED`

만료 폴백(stale fallback) 정책.

제어 대상: 라이브 애그리게이터가 실패하면(모든 공급자가 다운되거나 rate-limit 에 걸림), resolver 는 (a) from_expired_fallback: true 로 태그된 만료 캐시 항목을 반환하거나(true, 기본값), (b) 실패를 outcome: "none" 으로 처리(false)할 수 있습니다. 며칠 지난 토큰 해석에는 대개 오래된 데이터가 데이터 없음보다 낫습니다; 배포가 어떤 편차도 허용할 수 없으면 false 로 설정하십시오.
사용처: src/learning/canonical-asset-resolver.ts
미설정 시 기본값: true
허용 값: true / false / 1 / 0
설정 위치: 사용자 대상 설정 아님

하이브리드 메모리 검색

이 네 개의 변수는 임베딩으로 보강된 메모리 검색을 활성화합니다. EMBEDDING_PROVIDER 가 disabled(기본값)이면 스토어는 모든 행의 embedding_state='pending' 와 NULL embedding 컬럼을 그대로 두고, searchMemoriesHybrid 는 바이트 단위로 동일한 결과를 내는 Phase-A 이전 BM25 경로로 폴백합니다. 운영자는 시맨틱 리콜 향상을 원할 때만 이를 활성화합니다 — 그 시점부터 모든 writeMemory / writeRoleMemory 는 queueMicrotask 를 통해 비동기 임베딩을 예약합니다(쓰기 경로 지연 비용 없음). 실패는 절대 호출자에게 throw 되지 않습니다: embedding_state 컬럼이 'failed' / 'skipped' 로 이동하므로 minara doctor 가 적체를 감지할 수 있고, minara doctor --fix --apply 가 나중에 백필할 수 있습니다.

`EMBEDDING_PROVIDER`

어떤 공급자를 호출할지.

사용처: src/memory/embedding-provider.ts 의 createEmbeddingProviderFromEnv
Surfaced to: MemoryStore.searchMemoriesHybrid, MemoryStore.scheduleEmbedding, MemoryStore.backfillEmbeddings
허용 값: disabled | openai | voyage
미설정 시 기본값: disabled
disabled 이면 팩토리가 null 을 반환합니다 — 하이브리드 코드 경로가
완전히 비활성 상태이며 Phase-A 이전 코드처럼 동작합니다. EMBEDDING_API_KEY
도 함께 구성된 경우에만 실제 공급자로 설정하십시오; 그렇지 않으면
팩토리는 여전히 null 을 반환합니다(경고 로그와 함께).
설정 위치: 사용자 대상 설정 아님

`EMBEDDING_API_KEY`

구성된 공급자를 위한 bearer 토큰.

OpenAI: https://platform.openai.com/api-keys 에서 발급(sk-...).
Voyage: https://dash.voyageai.com/api-keys 에서 발급(pa-...).
미설정 시 기본값: (공급자가 null 을 반환, 하이브리드 경로 비활성)
형식: 불투명 문자열, 따옴표 불필요.
설정 위치: 설정 → API 키

`EMBEDDING_MODEL`

모델 식별자.

기본값은 각 공급자의 가장 저렴한 1536차원 모델을 따르므로 vec0 테이블
크기가 EMBEDDING_DIM 의 기본값과 정렬됩니다: - openai → text-embedding-3-small - voyage → voyage-3
차원이 일치함을 검증한 경우에만 재정의하십시오
EMBEDDING_DIM; 불일치는 임베딩 시점에 거부됩니다(경고 로그,
행은 'failed' 로 유지).
설정 위치: 사용자 대상 설정 아님

`EMBEDDING_DIM`

벡터 차원 수.

모델과 일치해야 합니다. 기본값: 1536. 부팅 시 vec0
가상 테이블(memories_vec, role_memory_vec)을 선언하는 데 사용됩니다 —
기존 DB 에서 이를 변경하려면 vec0 테이블의 수동 마이그레이션이
필요합니다(drop + recreate; 임베딩은 비권위적이므로
doctor --fix --apply 로 손실을 복구할 수 있음).
형식: 양의 정수.
설정 위치: 사용자 대상 설정 아님

`EMBEDDING_BASE_URL`

공급자 HTTP 엔드포인트에 대한 선택적 재정의.

미설정 시 기본값: 공급자 기본(provider-native) URL. - openai → https://api.openai.com/v1/embeddings - voyage → https://api.voyageai.com/v1/embeddings
자체 호스팅 게이트웨이나 프록시에 사용됩니다. 형식: 다음으로 끝나는 전체 URL —
/embeddings.
설정 위치: 사용자 대상 설정 아님

`SQLITE_VEC_EXTENSION_PATH`

sqlite-vec 로더블 확장 바이너리의 명시적 경로.

사용처: src/memory/memory-store.ts 의 MemoryStore.tryEnableVec
미설정 시 기본값: sqlite-vec npm 패키지에 번들된 플랫폼
바이너리(getLoadablePath() 로 해석). 운영자는 바이너리를 직접 관리할
때만 이를 설정합니다(예: 공유 시스템 경로, 커스텀
빌드, 또는 형제 sqlite-vec-<platform>-<arch> 패키지의 node_modules 를
제거하는 Docker 레이어).
형식: .so/.dylib/.dll 에 대한 절대 파일 시스템 경로. 로드
실패는 치명적이지 않습니다 — 하이브리드 경로가 조용히 순수 BM25 로 저하됩니다.
설정 위치: 사용자 대상 설정 아님

백테스팅 피드백 루프

목차