mcp-agents-memory 0.9.12 → 0.9.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.env.example +3 -0
  2. package/README.ko.md +298 -0
  3. package/README.md +158 -190
  4. package/build/index.js +524 -291
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,152 +1,153 @@
1
1
  # mcp-agents-memory
2
2
 
3
- > 사람의 기억을 모티브로 한, AI 에이전트들이 공유하는 장기 기억 MCP 서버.
3
+ > Long-term, time-ordered memory for AI agents — a shared memory pool that persists across sessions and machines, modeled on human memory.
4
4
 
5
- 여러 에이전트(Claude, Codex, ChatGPT, Hermes-Agent, OpenClaw 등)가 세션을 넘어 동일한 메모리 풀을 공유하며, 시간 순서대로 기억을 축적·회상하도록 설계.
5
+ Multiple agents (Claude Code, Codex, Gemini CLI, Grok, Antigravity, …) share **one** memory pool, accumulating and recalling memories in chronological order. Each platform/model gets its own view automatically, while project tags let collaborators see each other's relevant context.
6
6
 
7
- > **현재 fresh implementation 진행 중**. 이전 v0.x 시리즈는 `fact_type` 분류 axis로 짜여있어 form vision (시간 + 태그 + 임베딩)과 wrong axis. 상세 → [`RESPEC.md`](./RESPEC.md)
7
+ [![npm](https://img.shields.io/npm/v/mcp-agents-memory.svg)](https://www.npmjs.com/package/mcp-agents-memory)
8
+
9
+ > 🇰🇷 한국어 README → [`README.ko.md`](./README.ko.md)
10
+ > Design rationale and decisions → [`RESPEC.md`](./RESPEC.md)
8
11
 
9
12
  ---
10
13
 
11
- ## 모티브
14
+ ## Motivation
12
15
 
13
- - [**supermemory**](https://supermemory.io) — 시맨틱 그래프 기반 보편적 메모리 레이어
14
- - [**Hermes Agent**](https://github.com/NousResearch/hermes-agent) — MEMORY.md 스타일 자동 갱신, 스킬·규칙 시스템
16
+ - [**supermemory**](https://supermemory.io) — a universal, semantic-graph memory layer
17
+ - [**Hermes Agent**](https://github.com/NousResearch/hermes-agent) — `MEMORY.md`-style self-updating memory, skills & rules
15
18
 
16
- 이 두 프로젝트의 핵심을 합친 형태가 본 프로젝트의 목표.
19
+ This project aims to combine the strengths of both: supermemory's recall and Hermes' self-curation, without their weaknesses (machine-locked storage, opaque mutation).
17
20
 
18
21
  ---
19
22
 
20
- ## 핵심 설계
23
+ ## Core design
21
24
 
22
- 1. **사람 기억처럼 시간 순서**: 모든 대화가 시간 순서로 raw 저장. 별도 분류(fact_type) X. 시간이 지나면 태그 기반 요약 + 오래된 건 archive.
23
- 2. **자동 모델별 분리**: `agent_platform` / `agent_model` 컬럼만으로 모델별 기억 자동 분리. 별도 카테고리 만들 필요 없음.
24
- 3. **두 트랙 비동기**: Hot Path (raw 즉시 저장, 응답 빠름) ↔ Cold Path (백그라운드 사서가 1분 / 5메시지 단위로 태깅 + 임베딩).
25
- 4. **태그 중심 회상**: 단기는 최근 2-3일 raw, 장기는 태그 중심 요약. 과거 기록 필요 시 날짜 / 태그 / 키워드로 archive에서 retrieval.
25
+ 1. **Time-ordered, like human memory** — every turn is stored raw in chronological order. No `fact_type` taxonomy. Older memories are summarized by tag and archived (soft-delete, never destroyed).
26
+ 2. **Automatic per-model separation** — the `agent_platform` / `agent_model` columns alone separate memories per model. No manual categories.
27
+ 3. **Two asynchronous tracks** — a **Hot Path** (instant raw INSERT, fast response) and a **Cold Path** (a background "librarian" that tags, embeds, clusters, and curates on a 1-minute / 5-message cadence).
28
+ 4. **Tag-centric recall** — recent days as raw text, older history as tag-centric summaries. Anything older is retrievable from the archive by date / tag / keyword.
26
29
 
27
30
  ---
28
31
 
29
- ## 아키텍처
32
+ ## Architecture
30
33
 
31
- ### 두 트랙 비동기
34
+ ### Two asynchronous tracks
32
35
 
33
36
  ```
34
- ┌─────────────────┐ ┌─────────────────────────┐
35
- │ Agent │ │ MCP Server │
36
- │ (Claude Code, │ ───▶ │ ▶ Hot Path (즉시 저장) │ ──▶ memory 테이블
37
- │ Codex, ...) │ └─────────────────────────┘ (raw + role + platform/model)
37
+ ┌─────────────────┐ ┌──────────────────────────┐
38
+ │ Agent │ │ MCP Server │
39
+ │ (Claude Code, │ ───▶ │ ▶ Hot Path (instant save)│ ──▶ memory table
40
+ │ Codex, ...) │ └──────────────────────────┘ (raw + role + platform/model)
38
41
  └─────────────────┘ │
39
- │ p_tag/d_tag/embedding NULL인 row 누적
40
- ▼
41
- ┌─────────────────────────────┐
42
- │ Cold Path (1분 / 5메시지) │
43
- │ ├─ Tagger (gemini-2.5-flash)│ ──▶ p_tag, d_tag
44
- │ └─ Embedder (3-large) │ ──▶ embedding
45
- └─────────────────────────────┘
46
- │ 빈칸 UPDATE
42
+ │ rows with NULL p_tag/d_tag/embedding accumulate
47
43
  ▼
48
- ┌─────────────────────────────┐
49
- │ Librarian (memory → user) │ ──▶ user 테이블
50
- │ 핵심 사용자 정보 promote │ (core_profile / sub_profile)
51
- └─────────────────────────────┘
44
+ ┌──────────────────────────────┐
45
+ │ Cold Path (1 min / 5 msgs) │
46
+ │ ├─ Tagger → p_tag, d_tag │
47
+ │ ├─ Embedder → embedding │
48
+ │ ├─ Librarian → user profile │
49
+ │ ├─ Clusterer → tag summaries │
50
+ │ └─ AliasPromoter → tag merges │
51
+ └──────────────────────────────┘
52
52
  ```
53
53
 
54
- ### 데이터 모델
54
+ The Cold Path's LLM roles (tagger / librarian / clusterer / project-alias judge) all run on a **single shared backend** — local `Qwen3-14B` via llama.cpp, or a cloud fallback (see [Cold Path LLM backend](#cold-path-llm-backend)).
55
+
56
+ ### Data model
55
57
 
56
- **`memory` 테이블** — 시간 순서 raw 대화 저장 (단일 테이블, soft delete 아카이브)
58
+ **`memory`** — raw, time-ordered conversation log (single table, soft-delete archive)
57
59
 
58
- | 컬럼 | 설명 |
60
+ | Column | Notes |
59
61
  |---|---|
60
- | `user_id` | 사용자 식별 |
61
- | `agent_platform` | claude-code / codex / chatgpt / hermes-agent / openclaw 등 |
62
- | `agent_model` | opus-4-7 / gemini-3-pro / gpt-5.5 등 |
63
- | `subagent` | yes / no (1-level만 추적) |
64
- | `subagent_model` / `subagent_role` | sub일 때 채움. role은 free-form (lowercase normalize) |
62
+ | `user_id` | user identity |
63
+ | `agent_platform` | claude-code / codex / gemini-cli / grok / antigravity … |
64
+ | `agent_model` | e.g. opus-4-8 / gemini-3-pro / gpt-5.5 |
65
+ | `subagent` | yes / no (1 level tracked) |
66
+ | `subagent_model` / `subagent_role` | filled for subagents; role is free-form (lowercase-normalized) |
65
67
  | `role` | `user` / `assistant` |
66
- | `message` | raw 본문 |
67
- | `p_tag` | predefined (프로젝트 태그, `project_tags` 참조) |
68
- | `d_tag` | dynamic (문맥 태그) |
68
+ | `message` | raw body |
69
+ | `p_tag` | predefined project tag (→ `project_tags`) |
70
+ | `d_tag` | dynamic context tags |
69
71
  | `embedding` | `vector(3072)` — text-embedding-3-large |
70
- | `is_active` / `archived_at` | soft delete (무손실 보존) |
71
- | `is_pinned` | `manage_knowledge`로 강제 기억된 row, archive 면제 |
72
+ | `is_active` / `archived_at` | soft delete (lossless) |
73
+ | `is_pinned` | force-remembered via `manage_knowledge`; exempt from archival |
72
74
  | `created_at` / `updated_at` | |
73
75
 
74
- **`user` 테이블** — Librarian이 memory에서 핵심 정보 promote
76
+ **`users`** — core facts the Librarian promotes out of `memory`
75
77
 
76
- | 컬럼 | 설명 |
78
+ | Column | Notes |
77
79
  |---|---|
78
80
  | `user_id` / `user_name` | |
79
- | `core_profile` | 아주 중요한 핵심 사용자 정보 |
80
- | `sub_profile` | 그 외 기억해야 할 사용자 정보 |
81
- | `created_at` / `updated_at` | |
81
+ | `core_profile` | the most important, durable facts about the user |
82
+ | `sub_profile` | other facts worth remembering |
82
83
 
83
- **`project_tags` 테이블** — 프로젝트 태그 누적 (Cold Path가 동적 추가)
84
+ **`project_tags`** — project tags, grown dynamically by the Cold Path
84
85
 
85
- | 컬럼 | 설명 |
86
+ | Column | Notes |
86
87
  |---|---|
87
88
  | `id` / `name` / `description` | |
88
- | `alias_of` | 동의어 사후 병합용 (예: "centragens" ↔ "Centrazen 프로젝트") |
89
+ | `alias_of` | post-hoc merge of synonyms (e.g. "centragens" ↔ "Centrazen project") |
89
90
 
90
91
  ---
91
92
 
92
- ## 멀티머신 — 서버 / 클라이언트 (콜드패스 처리)
93
+ ## Multi-machine — server / client
93
94
 
94
- 여러 기기가 **하나의 공유 DB**를 쓸 때, Cold Path(태깅·프로필·클러스터링·alias 판정)는 **한 머신에서만** 돌아야 한다 — 안 그러면 같은 row를 여러 기기가 중복 처리하고 클라우드 비용이 배가된다. 같은 패키지를 **config로 역할만** 가른다:
95
+ When several machines share **one** database, the Cold Path (tagging / profiling / clustering / alias judging) must run on **exactly one** of them — otherwise machines double-process the same rows and double the cloud cost. The same package splits roles purely by **config**:
95
96
 
96
- | | 클라이언트 | 서버 (처리) |
97
+ | | Client | Server (processing) |
97
98
  |---|---|---|
98
- | **DB** | 원격 DB 접속 (SSH 터널 등) | DB 호스트 / 직접 접속 |
99
- | **Cold Path** | `COLD_PATH_ENABLED=false` | 전용 데몬으로 상시 가동 |
100
- | **하는 일** | `search` / `manage_knowledge`만 | 태깅 · 프로필 · 클러스터링 · alias 판정 |
101
- | **설정 난이도** | `.env` 몇 줄 (순수 config) | config + 로컬 LLM 인프라 |
99
+ | **DB** | remote (e.g. SSH tunnel) | DB host / direct |
100
+ | **Cold Path** | `COLD_PATH_ENABLED=false` | standalone daemon, always on |
101
+ | **Does** | `search` / `manage_knowledge` only | tagging · profiling · clustering · alias judging |
102
+ | **Setup** | a few `.env` lines | config + local LLM infra |
102
103
 
103
- - **클라이언트**: editor가 띄우는 MCP 서버가 그대로 단말. `.env`에 `COLD_PATH_ENABLED=false`만 추가하면 끝.
104
- - **서버**: Cold Path를 MCP(=editor) 수명과 분리해 **독립 데몬**으로 상시 가동 (editor를 안 켜도 처리됨):
104
+ - **Client**: the MCP server your editor spawns is the terminal. Just add `COLD_PATH_ENABLED=false`.
105
+ - **Server**: run the Cold Path decoupled from the editor's lifetime, as a standalone daemon (processes even when no editor is open):
105
106
  ```bash
106
- mcp-agents-memory coldpath # MCP 서버 없이 Cold Path 워커만 도는 데몬 (systemd 권장)
107
+ mcp-agents-memory coldpath # Cold Path worker only, no MCP server (systemd recommended)
107
108
  ```
108
- 데몬은 PostgreSQL advisory lock으로 **싱글톤** 보장 — 인스턴스가 몇 개든 락을 잡은 1개만 처리한다(중복 방지·자동 failover).
109
+ The daemon is a **singleton** via a PostgreSQL advisory lock — no matter how many instances exist, only the one holding the lock processes (dedup + automatic failover).
109
110
 
110
- ### Cold Path LLM 백엔드 (config로 교체)
111
+ ### Cold Path LLM backend
111
112
 
112
- `LOCAL_LLM_BASE_URL`로 OpenAI-호환 엔드포인트를 가리키면 로컬/셀프호스트 추론을 쓴다 (llama.cpp, ollama 등). 미설정 시 클라우드(`grok-4-1`) 기본. `LOCAL_GROK_FALLBACK=true`면 로컬 실패 시 grok으로 폴백.
113
+ Point `LOCAL_LLM_BASE_URL` at any OpenAI-compatible endpoint to use local / self-hosted inference (llama.cpp, ollama, …). If unset, a cloud model is used; `LOCAL_GROK_FALLBACK=true` falls back to Grok when local inference fails.
113
114
 
114
- > 예) AMD/NVIDIA GPU에 llama.cpp `llama-server`로 Qwen3-14B를 올리고 `LOCAL_LLM_BASE_URL=http://localhost:8080/v1` → 콜드패스 클라우드 비용 ≈ $0. (json_schema 문법 + thinking off로 valid JSON 보장)
115
+ > e.g. serve `Qwen3-14B` with llama.cpp `llama-server` on an AMD/NVIDIA GPU and set `LOCAL_LLM_BASE_URL=http://localhost:8080/v1` → Cold Path cloud cost ≈ $0. (A `json_schema` grammar with thinking disabled guarantees valid JSON.)
115
116
 
116
117
  ---
117
118
 
118
- ## 메모리 로드 룰
119
+ ## Memory load rules
119
120
 
120
- - **단기 메모리**: 최근 2-3일 raw 그대로, 또는 8000 토큰(약 12000-16000자) 중 먼저 도달하는 것
121
- - 토큰 측정은 char-approximate (`char_count / 1.7`) — Hot Path latency 보호
122
- - 단기/장기 전환 기간은 env로 tunable (form이 직접 조정 가능)
123
- - **모델 분리**: 기본 = 같은 `agent_platform` / `agent_model` 기억만. `p_tag` 매칭 시 (= 같은 프로젝트) 협업 agent 기억까지 포함
124
- - **archive 검색**: 사용자 발화 컨텍스트 ("며칠 전에...") 또는 과거 기록 필요 판단 시 → 날짜 / 태그 / 키워드로 archive에서 retrieval
125
- - **검색 fallback**: 의미 검색 (cosine) 결과 임계값 미만 시 ILIKE로 fallback (env tunable, 시작 0.3)
121
+ - **Short-term**: recent 2–3 days raw, or ~8000 tokens (whichever comes first). Token count is char-approximate (`chars / 1.7`) to protect Hot Path latency. Window is env-tunable.
122
+ - **Model separation**: by default, only memories with the same `agent_platform` / `agent_model`. A `p_tag` match (same project) pulls in collaborating agents' memories too.
123
+ - **Archive search**: on a user cue ("a few days ago…") or when older context is needed, retrieve from the archive by date / tag / keyword.
124
+ - **Search fallback**: when semantic (cosine) results fall below threshold, fall back to `ILIKE` (env-tunable, starts at 0.3).
126
125
 
127
126
  ---
128
127
 
129
- ## API (Tool 2개)
128
+ ## Tools
129
+
130
+ The server exposes **4 tools**. Most clients only ever need the first three; `save_message` is a fallback.
130
131
 
131
- ### `search_memory` — 조회/검색 통합
132
+ ### `memory_startup` — session boot brief
133
+ Returns a markdown brief (recent conversations, active projects, user profile) so a new session picks up where the last left off. On supported clients it is injected automatically at connect; call it explicitly to refresh mid-session.
132
134
 
135
+ ### `search_memory` — unified read / search
133
136
  ```ts
134
137
  search_memory({
135
- query?: string, // 의미 검색 (vector + ILIKE fallback)
136
- p_tag?: string, // 특정 프로젝트로 한정
137
- date_range?: string, // 기간 한정 (예: "2026-04-29..", "last_week")
138
- role?: 'user' | 'assistant', // user 발화만 / assistant 발화만 (기본 둘 다)
139
- agent_platform?: string, // 플랫폼 한정 (예: 'claude-code'). 생략 또는 '*' = 전 플랫폼
140
- device_scope?: 'local' | 'global', // 'global'(기본)=전 기기 / 'local'=현재 기기(pinned은 기기 무관)
141
- limit?: number, // 최대 결과 수 (기본 10, 최대 50)
142
- include_archived?: boolean, // archived 메모리 포함 (기본 false)
138
+ query?: string, // semantic search (vector + ILIKE fallback)
139
+ p_tag?: string, // restrict to a project
140
+ date_range?: string, // e.g. "2026-04-29..", "last_week"
141
+ role?: 'user' | 'assistant',
142
+ agent_platform?: string, // restrict to a platform; omit or '*' = all
143
+ device_scope?: 'local' | 'global', // 'global' (default) = all machines; 'local' = this one
144
+ limit?: number, // default 10, max 50
145
+ include_archived?: boolean,
143
146
  })
144
147
  ```
148
+ > "When you don't remember, reach for this one." Agents just vary the parameters.
145
149
 
146
- > "기억 안 나면 무조건 이거 하나만 써" — 에이전트가 파라미터 조합만 바꿔서 검색.
147
-
148
- ### `manage_knowledge` — 저장/수정 통합
149
-
150
+ ### `manage_knowledge` — unified write / edit
150
151
  ```ts
151
152
  manage_knowledge({
152
153
  action: 'add' | 'update' | 'remove',
@@ -154,145 +155,112 @@ manage_knowledge({
154
155
  content: string,
155
156
  })
156
157
  ```
158
+ > Use when the user explicitly says "remember this" / "forget that".
159
+ > `target='memory'` = force-remember (`is_pinned=true`, importance bump, archive-exempt).
160
+ > `manage_knowledge` skips the Cold Path and **syncs tag + embedding immediately**, so the memory is searchable the instant you say "got it".
157
161
 
158
- > 사용자가 명시적으로 "이건 기억해" / "이건 지워" 할 때 사용.
159
- > `target='memory'` 호출 = 강제 기억 (`is_pinned=true`, importance bump, archive 면제).
160
- > `manage_knowledge`만큼은 Cold Path 거치지 않고 **즉시 sync tag + embed**. ("기억했어요" 답한 직후 바로 검색 가능 보장)
161
-
162
- ---
162
+ ### `save_message` — transcript fallback
163
+ For platforms that **don't** auto-capture transcripts, the agent calls this each turn to persist the message. On auto-capturing clients (see below) it must **not** be called — that would duplicate rows.
163
164
 
164
- ## 기술 스택
165
+ ### Automatic capture
165
166
 
166
- | 역할 | 사용 기술 |
167
+ | Platform | Auto-capture |
167
168
  |---|---|
168
- | **Embedding** | OpenAI `text-embedding-3-large` (3072 dim) |
169
- | **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`로 선택 |
170
- | **검색 fallback** | PostgreSQL `ILIKE` (cosine 임계값 미만 시) |
171
- | **DB** | PostgreSQL + pgvector |
172
- | **Librarian (memory → user)** | 위 Cold Path 백엔드 공유 — recency-bias 저항 큐레이션(core 정체성 ↔ sub 작업 분리 + null-preserve), 게이트 env tunable |
173
- | **Skill 시스템** | TBD (다음 라운드) |
174
-
175
- ---
176
-
177
- ## 환경변수 (계획)
178
-
179
- ```bash
180
- # DB
181
- DB_HOST=...
182
- DB_PORT=5432
183
- DB_USER=...
184
- DB_PASS=...
185
- DB_NAME=...
186
-
187
- # SSH tunnel (옵션)
188
- SSH_ENABLED=true
189
- SSH_HOST=...
190
-
191
- # 모델
192
- EMBEDDING_MODEL=text-embedding-3-large
193
- OPENAI_API_KEY=... # embedding (필수)
194
- XAI_API_KEY=... # grok-4-1 (Cold Path 기본 + 로컬 폴백)
195
-
196
- # Cold Path LLM 백엔드 — 로컬 추론 쓰려면 OpenAI-호환 엔드포인트 지정 (없으면 클라우드)
197
- LOCAL_LLM_BASE_URL=http://localhost:8080/v1 # llama.cpp / ollama 등
198
- LOCAL_GROK_FALLBACK=true # 로컬 실패 시 grok 폴백
199
- TAGGER_PROVIDER=local # local / xai
200
- TAGGER_MODEL=qwen3-14b
201
- LIBRARIAN_PROVIDER=local
202
- LIBRARIAN_MODEL=qwen3-14b
203
- LIBRARIAN_ENABLED=true
204
- LIBRARIAN_MSG_THRESHOLD=30 # 라이브러리언 게이트 (기본 보수적)
205
- LIBRARIAN_COOLDOWN_HOURS=24
169
+ | Claude Code · Codex CLI · Gemini CLI · Grok Build · Antigravity CLI | ✅ transcript captured automatically — do **not** call `save_message` |
170
+ | Everything else | call `save_message(role=…)` each turn |
206
171
 
207
- # Hot/Cold path 제어
208
- COLD_PATH_ENABLED=true # false = 단말(Cold Path 안 돎). 멀티머신에선 처리 서버만 true
209
- COLD_PATH_INTERVAL_SEC=60 # 1분 단위 스케줄
210
- COLD_PATH_BATCH_SIZE=5 # 또는 5메시지 단위
211
-
212
- # 메모리 로드 tunable
213
- SHORT_TERM_DAYS=3 # 단기 메모리 윈도우
214
- SHORT_TERM_TOKEN_LIMIT=8000 # 토큰 리밋 (char-approx)
215
- SEARCH_FALLBACK_THRESHOLD=0.3 # cosine 미만 시 ILIKE fallback
216
-
217
- # Agent 식별 (caller가 self-report)
218
- AGENT_PLATFORM=claude-code
219
- AGENT_MODEL=opus-4-7
220
- AGENT_KEY=... # 옵션, multi-persona 구분용
221
- ```
172
+ > Auto-injection of the startup brief / auto-capture depends on the **client**, not the transport — some clients (e.g. desktop/web) don't expose those hooks, so they fall back to explicit tool calls.
222
173
 
223
174
  ---
224
175
 
225
- ## 상태
176
+ ## Tech stack
226
177
 
227
- | 항목 | 상태 |
178
+ | Role | Tech |
228
179
  |---|---|
229
- | `RESPEC.md` 작성 (vision + 결정사항 + nuance + 살릴 자산 / 폐기 코드) | ✅ Done |
230
- | 새 schema SQL (migration 019) | ✅ Done — `users` + `memory` + `project_tags` 3테이블 |
231
- | Hot Path 구현 (즉시 raw INSERT) | ✅ Done |
232
- | Cold Path 구현 (tagger gemini-2.5-flash + embedder 3-large + worker SKIP LOCKED) | ✅ Done |
233
- | Librarian 구현 (memory → user.core/sub_profile promote) | ✅ Done |
234
- | MCP Tools (`search_memory` + `manage_knowledge`) | ✅ Done |
235
- | Migration (legacy ~3582 row → archive 보존 + 재임베딩) | ✅ Done |
236
- | 핵심 정체성 promote (user.core_profile / sub_profile) | ✅ Done — Librarian v2 (gate + null guard + JSON-in-string guard, qwen3.6:35b-a3b) |
237
- | Skill 트랙 정리 | ⏳ form 결정 보류, 차후 |
180
+ | **Embedding** | OpenAI `text-embedding-3-large` (3072-dim) |
181
+ | **Cold Path LLM** (tagger / librarian / clusterer / project-alias judge) | local `Qwen3-14B` (llama.cpp; `json_schema` grammar + thinking off → valid JSON), **or** cloud `grok-4-1-fast-non-reasoning` fallback — selected via `LOCAL_LLM_BASE_URL` |
182
+ | **Search fallback** | PostgreSQL `ILIKE` (below cosine threshold) |
183
+ | **DB** | PostgreSQL + pgvector |
184
+ | **Librarian** (memory → users) | shares the Cold Path backend — recency-bias-resistant curation (core identity ↔ sub work split, null-preserve), gated by env-tunable thresholds |
238
185
 
239
186
  ---
240
187
 
241
- ## 참조 문서
188
+ ## Environment variables
242
189
 
243
- - [`RESPEC.md`](./RESPEC.md) — 현재 vision + 회의 결정사항 + 구현 detail (단일 진실 원천)
244
- - [`SPEC.md`](./SPEC.md) — 구 SPEC (v0.x 역사 보존, 일부 §3.4 Memory Tier가 본 vision의 원형)
245
- - [`DEVLOG.md`](./DEVLOG.md) — 운영 이슈, 관찰 로그, 아이디어 적립
190
+ See [`.env.example`](./.env.example) for the full, annotated list. The essentials:
246
191
 
247
- ---
248
-
249
- ## 가이드 원칙
192
+ ```bash
193
+ # DB
194
+ DB_HOST=... DB_PORT=5432 DB_USER=... DB_PASS=... DB_NAME=...
250
195
 
251
- > 눈앞 문제 해결한다고 전체 구조가 망가지면 안 됨.
196
+ # Keys
197
+ OPENAI_API_KEY=... # embedding (required)
198
+ XAI_API_KEY=... # Grok (Cold Path cloud + local fallback)
252
199
 
253
- 매 작업/제안 시 RESPEC.md vision 정합 검증 → "이 fix가 큰 틀과 맞나?" 확인 후 진행.
254
- "일단 돌게만 만들자"는 멈춤 신호.
200
+ # Cold Path LLM backend — OpenAI-compatible endpoint for local inference (omit → cloud)
201
+ LOCAL_LLM_BASE_URL=http://localhost:8080/v1
202
+ LOCAL_GROK_FALLBACK=true
203
+ TAGGER_PROVIDER=local TAGGER_MODEL=qwen3-14b
204
+ LIBRARIAN_PROVIDER=local LIBRARIAN_MODEL=qwen3-14b
205
+ LIBRARIAN_ENABLED=true
255
206
 
256
- ---
207
+ # Hot/Cold path control
208
+ COLD_PATH_ENABLED=true # false = client terminal (no Cold Path); only the server is true
209
+ COLD_PATH_INTERVAL_SEC=60
210
+ COLD_PATH_BATCH_SIZE=5
257
211
 
258
- *Status: fresh implementation 준비 단계. 실제 구현은 form 결정 후 진행.*
212
+ # Memory load tunables
213
+ SHORT_TERM_DAYS=3
214
+ SHORT_TERM_TOKEN_LIMIT=8000
215
+ SEARCH_FALLBACK_THRESHOLD=0.3
259
216
 
217
+ # Agent identity (caller self-reports)
218
+ AGENT_PLATFORM=claude-code
219
+ AGENT_MODEL=opus-4-8
220
+ ```
260
221
 
222
+ ---
261
223
 
262
- gemini cli trust setting 방법
224
+ ## Client setup
263
225
 
264
- ~/.gemini/settings.json
226
+ ### Claude Code / Codex
227
+ ```toml
228
+ # ~/.codex/config.toml
229
+ [mcp_servers.mcp-agents-memory]
230
+ command = "mcp-agents-memory"
231
+ args = []
232
+ ```
265
233
 
234
+ ### Gemini CLI
266
235
  ```json
267
- "mcpServers": {
236
+ // ~/.gemini/settings.json
237
+ {
238
+ "mcpServers": {
268
239
  "mcp-agents-memory": {
269
240
  "type": "stdio",
270
- "command": "node",
271
- "args": [
272
- "/Users/hoon/Documents/Playgrounds/mcp-agents-memory/build/index.js"
273
- ],
241
+ "command": "mcp-agents-memory",
242
+ "args": [],
274
243
  "env": {},
275
- "trust": true
244
+ "trust": true
276
245
  }
277
246
  }
247
+ }
278
248
  ```
279
249
 
280
- codex
250
+ > Install globally with `npm i -g mcp-agents-memory`, or point `command` at a local `build/index.js`.
281
251
 
282
- ~/.codex/config.toml
252
+ ---
283
253
 
284
- ```toml
285
- [mcp_servers.mcp-agents-memory]
286
- command = "mcp-agents-memory"
287
- args = []
254
+ ## Guiding principle
288
255
 
289
- [mcp_servers.mcp-agents-memory.tools.memory_startup]
290
- approval_mode = "approve"
256
+ > Solving the problem in front of you must not break the whole structure.
291
257
 
292
- [mcp_servers.mcp-agents-memory.tools.save_message]
293
- approval_mode = "approve"
258
+ Every change is checked against the `RESPEC.md` vision — "does this fix fit the big picture?" — before proceeding. "Just make it run" is a stop signal.
294
259
 
295
- [mcp_servers.mcp-agents-memory.tools.search_memory]
296
- approval_mode = "approve"
297
- ```
260
+ ---
261
+
262
+ ## Reference docs
298
263
 
264
+ - [`RESPEC.md`](./RESPEC.md) — current vision, decisions, implementation detail (single source of truth)
265
+ - [`DEVLOG.md`](./DEVLOG.md) — operational issues, observations, ideas
266
+ - [`README.ko.md`](./README.ko.md) — Korean README