mcp-agents-memory 0.9.6 → 0.9.11

package/.env.example

@@ -110,3 +110,32 @@ FORGETTING_ENABLED=false
 FORGETTING_WARMUP_MIN=30
 FORGETTING_INTERVAL_MIN=1440
 FORGET_THRESHOLD=0.5
+
+# Project Alias Promoter (Stage 2) — cold path alias suggestions; default OFF, auto-apply requires explicit opt-in.
+PROJECT_ALIAS_PROMOTER_ENABLED=false
+PROJECT_ALIAS_PROMOTER_INTERVAL_HOURS=24
+PROJECT_ALIAS_AUTO_APPLY=false
+
+# ─────────────────────────────────────────────────────────────
+# Local LLM (ollama) — API 비용 없이 추론 가능한 역할에 적용
+# 대상: AMD RX 6800 XT (gfx1030, 16GB VRAM) + ROCm 7.1
+#
+# 설치:  bash scripts/setup_local_llm.sh
+# 벤치:  npx tsx scripts/bench_local_tagger.ts
+# ─────────────────────────────────────────────────────────────
+
+# ollama 서버 주소 (기본: localhost:11434)
+# LOCAL_LLM_BASE_URL=http://localhost:11434/v1
+
+# 태거를 로컬 모델로 교체 (기본: xai/grok)
+# 벤치 PASS 모델: qwen2.5:7b (100% JSON 성공, avg 754ms)
+# qwen3.x 계열은 ollama에서 thinking 비활성화 불가 → content 빈 버그 있음
+# TAGGER_PROVIDER=local
+# TAGGER_MODEL=qwen2.5:7b
+
+# 라이브러리언을 로컬 모델로 교체 (Librarian v2 구현 후 활성화)
+# LIBRARIAN_PROVIDER=local
+# LIBRARIAN_MODEL=qwen3.6:35b-a3b
+
+# 로컬 모델 실패 시 grok으로 자동 fallback (기본: true)
+# LOCAL_GROK_FALLBACK=true

package/README.md

@@ -89,6 +89,32 @@
 
 ---
 
+## 멀티머신 — 서버 / 클라이언트 (콜드패스 처리)
+
+여러 기기가 **하나의 공유 DB**를 쓸 때, Cold Path(태깅·프로필·클러스터링·alias 판정)는 **한 머신에서만** 돌아야 한다 — 안 그러면 같은 row를 여러 기기가 중복 처리하고 클라우드 비용이 배가된다. 같은 패키지를 **config로 역할만** 가른다:
+
+| | 클라이언트 | 서버 (처리) |
+|---|---|---|
+| **DB** | 원격 DB 접속 (SSH 터널 등) | DB 호스트 / 직접 접속 |
+| **Cold Path** | `COLD_PATH_ENABLED=false` | 전용 데몬으로 상시 가동 |
+| **하는 일** | `search` / `manage_knowledge`만 | 태깅 · 프로필 · 클러스터링 · alias 판정 |
+| **설정 난이도** | `.env` 몇 줄 (순수 config) | config + 로컬 LLM 인프라 |
+
+- **클라이언트**: editor가 띄우는 MCP 서버가 그대로 단말. `.env`에 `COLD_PATH_ENABLED=false`만 추가하면 끝.
+- **서버**: Cold Path를 MCP(=editor) 수명과 분리해 **독립 데몬**으로 상시 가동 (editor를 안 켜도 처리됨):
+  ```bash
+  mcp-agents-memory coldpath    # MCP 서버 없이 Cold Path 워커만 도는 데몬 (systemd 권장)
+  ```
+  데몬은 PostgreSQL advisory lock으로 **싱글톤** 보장 — 인스턴스가 몇 개든 락을 잡은 1개만 처리한다(중복 방지·자동 failover).
+
+### Cold Path LLM 백엔드 (config로 교체)
+
+`LOCAL_LLM_BASE_URL`로 OpenAI-호환 엔드포인트를 가리키면 로컬/셀프호스트 추론을 쓴다 (llama.cpp, ollama 등). 미설정 시 클라우드(`grok-4-1`) 기본. `LOCAL_GROK_FALLBACK=true`면 로컬 실패 시 grok으로 폴백.
+
+> 예) AMD/NVIDIA GPU에 llama.cpp `llama-server`로 Qwen3-14B를 올리고 `LOCAL_LLM_BASE_URL=http://localhost:8080/v1` → 콜드패스 클라우드 비용 ≈ $0. (json_schema 문법 + thinking off로 valid JSON 보장)
+
+---
+
 ## 메모리 로드 룰
 
 - **단기 메모리**: 최근 2-3일 raw 그대로, 또는 8000 토큰(약 12000-16000자) 중 먼저 도달하는 것
@@ -109,7 +135,11 @@ search_memory({
   query?: string,        // 의미 검색 (vector + ILIKE fallback)
   p_tag?: string,        // 특정 프로젝트로 한정
   date_range?: string,   // 기간 한정 (예: "2026-04-29..", "last_week")
-  role?: 'user' | 'assistant',  // form 발화만 / assistant 발화만 (기본 둘 다)
+  role?: 'user' | 'assistant',  // user 발화만 / assistant 발화만 (기본 둘 다)
+  agent_platform?: string,      // 플랫폼 한정 (예: 'claude-code'). 생략 또는 '*' = 전 플랫폼
+  device_scope?: 'local' | 'global',  // 'global'(기본)=전 기기 / 'local'=현재 기기(pinned은 기기 무관)
+  limit?: number,        // 최대 결과 수 (기본 10, 최대 50)
+  include_archived?: boolean,   // archived 메모리 포함 (기본 false)
 })
 ```
 
@@ -136,10 +166,10 @@ manage_knowledge({
 | 역할 | 사용 기술 |
 |---|---|
 | **Embedding** | OpenAI `text-embedding-3-large` (3072 dim) |
-| **Tagger (Cold Path)** | Google `gemini-2.5-flash` (predefined + dynamic) |
+| **Cold Path LLM** (tagger / librarian / clusterer / project-alias judge) | 로컬 `Qwen3-14B` (llama.cpp, json_schema 문법 + thinking off → valid JSON 보장) **또는** 클라우드 `grok-4-1-fast-non-reasoning` — `LOCAL_LLM_BASE_URL`로 선택 |
 | **검색 fallback** | PostgreSQL `ILIKE` (cosine 임계값 미만 시) |
 | **DB** | PostgreSQL + pgvector |
-| **Librarian (memory → user)** | TBD (form vision 결정 후) |
+| **Librarian (memory → user)** | 위 Cold Path 백엔드 공유 — recency-bias 저항 큐레이션(core 정체성 ↔ sub 작업 분리 + null-preserve), 게이트 env tunable |
 | **Skill 시스템** | TBD (다음 라운드) |
 
 ---
@@ -160,11 +190,22 @@ SSH_HOST=...
 
 # 모델
 EMBEDDING_MODEL=text-embedding-3-large
-TAGGER_MODEL=gemini-2.5-flash
-OPENAI_API_KEY=...
-GEMINI_API_KEY=...
+OPENAI_API_KEY=...                 # embedding (필수)
+XAI_API_KEY=...                    # grok-4-1 (Cold Path 기본 + 로컬 폴백)
+
+# Cold Path LLM 백엔드 — 로컬 추론 쓰려면 OpenAI-호환 엔드포인트 지정 (없으면 클라우드)
+LOCAL_LLM_BASE_URL=http://localhost:8080/v1   # llama.cpp / ollama 등
+LOCAL_GROK_FALLBACK=true           # 로컬 실패 시 grok 폴백
+TAGGER_PROVIDER=local              # local / xai
+TAGGER_MODEL=qwen3-14b
+LIBRARIAN_PROVIDER=local
+LIBRARIAN_MODEL=qwen3-14b
+LIBRARIAN_ENABLED=true
+LIBRARIAN_MSG_THRESHOLD=30         # 라이브러리언 게이트 (기본 보수적)
+LIBRARIAN_COOLDOWN_HOURS=24
 
 # Hot/Cold path 제어
+COLD_PATH_ENABLED=true             # false = 단말(Cold Path 안 돎). 멀티머신에선 처리 서버만 true
 COLD_PATH_INTERVAL_SEC=60          # 1분 단위 스케줄
 COLD_PATH_BATCH_SIZE=5             # 또는 5메시지 단위
 
@@ -192,7 +233,7 @@ AGENT_KEY=...                      # 옵션, multi-persona 구분용
 | Librarian 구현 (memory → user.core/sub_profile promote) | ✅ Done |
 | MCP Tools (`search_memory` + `manage_knowledge`) | ✅ Done |
 | Migration (legacy ~3582 row → archive 보존 + 재임베딩) | ✅ Done |
-| 핵심 정체성 promote (user.core_profile / sub_profile) | ✅ Done — Librarian draft + form review |
+| 핵심 정체성 promote (user.core_profile / sub_profile) | ✅ Done — Librarian v2 (gate + null guard + JSON-in-string guard, qwen3.6:35b-a3b) |
 | Skill 트랙 정리 | ⏳ form 결정 보류, 차후 |
 
 ---
@@ -201,7 +242,7 @@ AGENT_KEY=...                      # 옵션, multi-persona 구분용
 
 - [`RESPEC.md`](./RESPEC.md) — 현재 vision + 회의 결정사항 + 구현 detail (단일 진실 원천)
 - [`SPEC.md`](./SPEC.md) — 구 SPEC (v0.x 역사 보존, 일부 §3.4 Memory Tier가 본 vision의 원형)
-- [`PROBLEMS.md`](./PROBLEMS.md) — 현재 진행 중 cleanup 단계 / 진단 결과
+- [`DEVLOG.md`](./DEVLOG.md) — 운영 이슈, 관찰 로그, 아이디어 적립
 
 ---
 

package/RESPEC.md

@@ -128,9 +128,13 @@ Tokens $0.50/ 1M tokens
 
 
 
-**Librarian**
+**Librarian** ✅ v2 완성 (2026-05-22)
 
 - memory table 에서 필요한 user 테이블용 정보를 선별해서 user 테이블에 저장
+- 모델: `qwen3.6:35b-a3b` (local/ollama, Q4_K_M) — thinking 허용, max_tokens=32768
+- 게이트: `LIBRARIAN_ENABLED=true` + 30 새 메시지 + 24h 쿨다운
+- 실패 방어: attempt 시 `last_run_at` 즉시 기록 (hammer 방지), null guard, JSON-in-string guard
+- Cold Path worker tick마다 `maybeRunLibrarian()` 호출 (migration 023)