mcp-agents-memory 0.8.0 → 0.8.2
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.
- package/README.md +178 -127
- package/README.md.back.md +166 -0
- package/RESPEC.md +245 -0
- package/build/index.js +22997 -84227
- package/build/migrations/018_transcript_queue.js +26005 -0
- package/build/migrations/019_respec_fresh_v1.js +26125 -0
- package/build/migrations/020_tag_processed_and_external_uuid.js +26003 -0
- package/build/migrations/021_agent_model_nullable.js +25989 -0
- package/package.json +4 -3
- package/README_KR.md +0 -113
package/README.md
CHANGED
|
@@ -1,166 +1,217 @@
|
|
|
1
|
-
# mcp-agents-memory
|
|
1
|
+
# mcp-agents-memory
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
An MCP server that enables AI agents (Claude, Gemini, GPT, etc.) to **autonomously manage memory** and evolve knowledge into **validated operational rules (Skills)**.
|
|
3
|
+
> 사람의 기억을 모티브로 한, AI 에이전트들이 공유하는 장기 기억 MCP 서버.
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
여러 에이전트(Claude, Codex, ChatGPT, Hermes-Agent, OpenClaw 등)가 세션을 넘어 동일한 메모리 풀을 공유하며, 시간 순서대로 기억을 축적·회상하도록 설계.
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
- **🦾 Skill Evolution**: Repetitive patterns and project know-how automatically evolve into **Skills**. These rules are injected into the agent's system prompt to guide future actions.
|
|
10
|
-
- **🌐 Authority Grounding**: High-value facts are reconciled against external authority sources (**Tavily** for recency, **Exa** for authority/docs) before storage.
|
|
11
|
-
- **⚡ MCP Prompts (Slash Commands)**: Direct interaction via `/briefing`, `/recall <query>`, and `/save <text>` for a premium UX.
|
|
12
|
-
- **🔐 Cross-MCP Ready**: Standardized context hooks to share `subject_key` and `session_id` with other MCPs (Vision, Audio, etc.).
|
|
7
|
+
> **현재 fresh implementation 진행 중**. 이전 v0.x 시리즈는 `fact_type` 분류 axis로 짜여있어 form vision (시간 + 태그 + 임베딩)과 wrong axis. 상세 → [`RESPEC.md`](./RESPEC.md)
|
|
13
8
|
|
|
14
|
-
|
|
9
|
+
---
|
|
15
10
|
|
|
16
|
-
|
|
17
|
-
- **⚡ Contradiction Resolution**: Detects and updates conflicting information (e.g., "Lives in Seoul" → "Moved to Busan").
|
|
18
|
-
- **🧠 Smart Briefing**: Dynamic session startup with user profile, project context, and applicable **Skills**.
|
|
19
|
-
- **🔍 Semantic Search**: Vector embedding-based retrieval with automatic tier-up for matching long-term memories.
|
|
20
|
-
- **🔐 Unified Provenance**: Every fact is tagged with `author_model`, `platform`, and `session_id` for perfect traceability.
|
|
11
|
+
## 모티브
|
|
21
12
|
|
|
22
|
-
|
|
13
|
+
- [**supermemory**](https://supermemory.io) — 시맨틱 그래프 기반 보편적 메모리 레이어
|
|
14
|
+
- [**Hermes Agent**](https://github.com/NousResearch/hermes-agent) — MEMORY.md 스타일 자동 갱신, 스킬·규칙 시스템
|
|
23
15
|
|
|
24
|
-
|
|
16
|
+
이 두 프로젝트의 핵심을 합친 형태가 본 프로젝트의 목표.
|
|
25
17
|
|
|
26
|
-
|
|
27
|
-
|----------|------------|-------------|
|
|
28
|
-
| **Skill Auditor** | Anthropic `Sonnet` / `Gemini Pro` | **Grounding**: Reconciles facts with external docs using Tavily + Exa. |
|
|
29
|
-
| **Skill Curator** | Google `Gemini Flash` | **Promotion**: Monitors memory clusters to identify skill candidates. |
|
|
30
|
-
| **Fact Extractor** | OpenAI `gpt-4o-mini` | **Extraction**: Efficient atomic fact generation from text. |
|
|
31
|
-
| **Embedding** | OpenAI `text-embedding-3-small` | **Standard**: 1536-dim vector indexing for semantic search. |
|
|
32
|
-
| **Search (Required)** | **Tavily + Exa** | **The Two Pillars**: Tavily (Recency) + Exa (Authority/Research). |
|
|
33
|
-
| **Database** | PostgreSQL + pgvector | **Tiered Storage**: Tier-aware partitioning (Short/Long term). |
|
|
18
|
+
---
|
|
34
19
|
|
|
35
|
-
##
|
|
20
|
+
## 핵심 설계
|
|
36
21
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
└────────┬────────┘ └──────┬───────┘ └──────┬───────┘
|
|
42
|
-
│ │ │
|
|
43
|
-
└─────────────────────┼────────────────────┘
|
|
44
|
-
│
|
|
45
|
-
┌──────────▼──────────┐
|
|
46
|
-
│ MCP Protocol │
|
|
47
|
-
│ (w/ instructions) │ ← Zero-Config Entry
|
|
48
|
-
└──────────┬──────────┘
|
|
49
|
-
│
|
|
50
|
-
┌──────────▼──────────┐ ┌──────────────────┐
|
|
51
|
-
│ mcp-agents-memory │ │ Skill Track │
|
|
52
|
-
│ ┌───────────────┐ │ ───▶ │ Curator/Auditor │
|
|
53
|
-
│ │ Librarian │ │ │ (Knowledge/Web) │
|
|
54
|
-
│ │ Engine │ │ └────────┬─────────┘
|
|
55
|
-
│ └───────┬───────┘ │ │
|
|
56
|
-
└──────────┼──────────┘ ┌────────▼─────────┐
|
|
57
|
-
│ │ Skills Table │
|
|
58
|
-
┌──────────▼──────────┐ │ (Operational) │
|
|
59
|
-
│ PostgreSQL + pgvec │ └──────────────────┘
|
|
60
|
-
│ (Tiered Memories) │
|
|
61
|
-
└─────────────────────┘
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
## Setup
|
|
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.
|
|
65
26
|
|
|
66
|
-
|
|
27
|
+
---
|
|
67
28
|
|
|
68
|
-
|
|
69
|
-
npm i -g mcp-agents-memory
|
|
70
|
-
```
|
|
29
|
+
## 아키텍처
|
|
71
30
|
|
|
72
|
-
###
|
|
31
|
+
### 두 트랙 비동기
|
|
73
32
|
|
|
74
|
-
```
|
|
75
|
-
|
|
33
|
+
```
|
|
34
|
+
┌─────────────────┐ ┌─────────────────────────┐
|
|
35
|
+
│ Agent │ │ MCP Server │
|
|
36
|
+
│ (Claude Code, │ ───▶ │ ▶ Hot Path (즉시 저장) │ ──▶ memory 테이블
|
|
37
|
+
│ Codex, ...) │ └─────────────────────────┘ (raw + role + platform/model)
|
|
38
|
+
└─────────────────┘ │
|
|
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
|
|
47
|
+
▼
|
|
48
|
+
┌─────────────────────────────┐
|
|
49
|
+
│ Librarian (memory → user) │ ──▶ user 테이블
|
|
50
|
+
│ 핵심 사용자 정보 promote │ (core_profile / sub_profile)
|
|
51
|
+
└─────────────────────────────┘
|
|
76
52
|
```
|
|
77
53
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
54
|
+
### 데이터 모델
|
|
55
|
+
|
|
56
|
+
**`memory` 테이블** — 시간 순서 raw 대화 저장 (단일 테이블, soft delete 아카이브)
|
|
57
|
+
|
|
58
|
+
| 컬럼 | 설명 |
|
|
59
|
+
|---|---|
|
|
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) |
|
|
65
|
+
| `role` | `user` / `assistant` |
|
|
66
|
+
| `message` | raw 본문 |
|
|
67
|
+
| `p_tag` | predefined (프로젝트 태그, `project_tags` 참조) |
|
|
68
|
+
| `d_tag` | dynamic (문맥 태그) |
|
|
69
|
+
| `embedding` | `vector(3072)` — text-embedding-3-large |
|
|
70
|
+
| `is_active` / `archived_at` | soft delete (무손실 보존) |
|
|
71
|
+
| `is_pinned` | `manage_knowledge`로 강제 기억된 row, archive 면제 |
|
|
72
|
+
| `created_at` / `updated_at` | |
|
|
73
|
+
|
|
74
|
+
**`user` 테이블** — Librarian이 memory에서 핵심 정보 promote
|
|
75
|
+
|
|
76
|
+
| 컬럼 | 설명 |
|
|
77
|
+
|---|---|
|
|
78
|
+
| `user_id` / `user_name` | |
|
|
79
|
+
| `core_profile` | 아주 중요한 핵심 사용자 정보 |
|
|
80
|
+
| `sub_profile` | 그 외 기억해야 할 사용자 정보 |
|
|
81
|
+
| `created_at` / `updated_at` | |
|
|
82
|
+
|
|
83
|
+
**`project_tags` 테이블** — 프로젝트 태그 누적 (Cold Path가 동적 추가)
|
|
84
|
+
|
|
85
|
+
| 컬럼 | 설명 |
|
|
86
|
+
|---|---|
|
|
87
|
+
| `id` / `name` / `description` | |
|
|
88
|
+
| `alias_of` | 동의어 사후 병합용 (예: "centragens" ↔ "Centrazen 프로젝트") |
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## 메모리 로드 룰
|
|
93
|
+
|
|
94
|
+
- **단기 메모리**: 최근 2-3일 raw 그대로, 또는 8000 토큰(약 12000-16000자) 중 먼저 도달하는 것
|
|
95
|
+
- 토큰 측정은 char-approximate (`char_count / 1.7`) — Hot Path latency 보호
|
|
96
|
+
- 단기/장기 전환 기간은 env로 tunable (form이 직접 조정 가능)
|
|
97
|
+
- **모델 분리**: 기본 = 같은 `agent_platform` / `agent_model` 기억만. `p_tag` 매칭 시 (= 같은 프로젝트) 협업 agent 기억까지 포함
|
|
98
|
+
- **archive 검색**: 사용자 발화 컨텍스트 ("며칠 전에...") 또는 과거 기록 필요 판단 시 → 날짜 / 태그 / 키워드로 archive에서 retrieval
|
|
99
|
+
- **검색 fallback**: 의미 검색 (cosine) 결과 임계값 미만 시 ILIKE로 fallback (env tunable, 시작 0.3)
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## API (Tool 2개)
|
|
104
|
+
|
|
105
|
+
### `search_memory` — 조회/검색 통합
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
search_memory({
|
|
109
|
+
query?: string, // 의미 검색 (vector + ILIKE fallback)
|
|
110
|
+
p_tag?: string, // 특정 프로젝트로 한정
|
|
111
|
+
date_range?: string, // 기간 한정 (예: "2026-04-29..", "last_week")
|
|
112
|
+
role?: 'user' | 'assistant', // form 발화만 / assistant 발화만 (기본 둘 다)
|
|
113
|
+
})
|
|
101
114
|
```
|
|
102
115
|
|
|
103
|
-
|
|
116
|
+
> "기억 안 나면 무조건 이거 하나만 써" — 에이전트가 파라미터 조합만 바꿔서 검색.
|
|
104
117
|
|
|
105
|
-
`
|
|
118
|
+
### `manage_knowledge` — 저장/수정 통합
|
|
106
119
|
|
|
107
|
-
|
|
120
|
+
```ts
|
|
121
|
+
manage_knowledge({
|
|
122
|
+
action: 'add' | 'update' | 'remove',
|
|
123
|
+
target: 'sub_profile' | 'memory',
|
|
124
|
+
content: string,
|
|
125
|
+
})
|
|
126
|
+
```
|
|
108
127
|
|
|
109
|
-
|
|
128
|
+
> 사용자가 명시적으로 "이건 기억해" / "이건 지워" 할 때 사용.
|
|
129
|
+
> `target='memory'` 호출 = 강제 기억 (`is_pinned=true`, importance bump, archive 면제).
|
|
130
|
+
> `manage_knowledge`만큼은 Cold Path 거치지 않고 **즉시 sync tag + embed**. ("기억했어요" 답한 직후 바로 검색 가능 보장)
|
|
110
131
|
|
|
111
|
-
|
|
132
|
+
---
|
|
112
133
|
|
|
113
|
-
|
|
114
|
-
- `mcp-agents-memory setup` — interactive wizard (writes XDG config, applies schema + migrations).
|
|
115
|
-
- `mcp-agents-memory migrate` — apply pending migrations against an already-configured database.
|
|
116
|
-
- `mcp-agents-memory help` — show help.
|
|
134
|
+
## 기술 스택
|
|
117
135
|
|
|
118
|
-
|
|
136
|
+
| 역할 | 사용 기술 |
|
|
137
|
+
|---|---|
|
|
138
|
+
| **Embedding** | OpenAI `text-embedding-3-large` (3072 dim) |
|
|
139
|
+
| **Tagger (Cold Path)** | Google `gemini-2.5-flash` (predefined + dynamic) |
|
|
140
|
+
| **검색 fallback** | PostgreSQL `ILIKE` (cosine 임계값 미만 시) |
|
|
141
|
+
| **DB** | PostgreSQL + pgvector |
|
|
142
|
+
| **Librarian (memory → user)** | TBD (form vision 결정 후) |
|
|
143
|
+
| **Skill 시스템** | TBD (다음 라운드) |
|
|
119
144
|
|
|
120
|
-
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 환경변수 (계획)
|
|
121
148
|
|
|
122
149
|
```bash
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
150
|
+
# DB
|
|
151
|
+
DB_HOST=...
|
|
152
|
+
DB_PORT=5432
|
|
153
|
+
DB_USER=...
|
|
154
|
+
DB_PASS=...
|
|
155
|
+
DB_NAME=...
|
|
156
|
+
|
|
157
|
+
# SSH tunnel (옵션)
|
|
158
|
+
SSH_ENABLED=true
|
|
159
|
+
SSH_HOST=...
|
|
160
|
+
|
|
161
|
+
# 모델
|
|
162
|
+
EMBEDDING_MODEL=text-embedding-3-large
|
|
163
|
+
TAGGER_MODEL=gemini-2.5-flash
|
|
164
|
+
OPENAI_API_KEY=...
|
|
165
|
+
GEMINI_API_KEY=...
|
|
166
|
+
|
|
167
|
+
# Hot/Cold path 제어
|
|
168
|
+
COLD_PATH_INTERVAL_SEC=60 # 1분 단위 스케줄
|
|
169
|
+
COLD_PATH_BATCH_SIZE=5 # 또는 5메시지 단위
|
|
170
|
+
|
|
171
|
+
# 메모리 로드 tunable
|
|
172
|
+
SHORT_TERM_DAYS=3 # 단기 메모리 윈도우
|
|
173
|
+
SHORT_TERM_TOKEN_LIMIT=8000 # 토큰 리밋 (char-approx)
|
|
174
|
+
SEARCH_FALLBACK_THRESHOLD=0.3 # cosine 미만 시 ILIKE fallback
|
|
175
|
+
|
|
176
|
+
# Agent 식별 (caller가 self-report)
|
|
177
|
+
AGENT_PLATFORM=claude-code
|
|
178
|
+
AGENT_MODEL=opus-4-7
|
|
179
|
+
AGENT_KEY=... # 옵션, multi-persona 구분용
|
|
128
180
|
```
|
|
129
181
|
|
|
130
|
-
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## 상태
|
|
131
185
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
186
|
+
| 항목 | 상태 |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `RESPEC.md` 작성 (vision + 결정사항 + nuance + 살릴 자산 / 폐기 코드) | ✅ Done |
|
|
189
|
+
| 새 schema SQL (migration 019) | ✅ Done — `users` + `memory` + `project_tags` 3테이블 |
|
|
190
|
+
| Hot Path 구현 (즉시 raw INSERT) | ✅ Done |
|
|
191
|
+
| Cold Path 구현 (tagger gemini-2.5-flash + embedder 3-large + worker SKIP LOCKED) | ✅ Done |
|
|
192
|
+
| Librarian 구현 (memory → user.core/sub_profile promote) | ✅ Done |
|
|
193
|
+
| MCP Tools (`search_memory` + `manage_knowledge`) | ✅ Done |
|
|
194
|
+
| Migration (legacy ~3582 row → archive 보존 + 재임베딩) | ✅ Done |
|
|
195
|
+
| 핵심 정체성 promote (user.core_profile / sub_profile) | ✅ Done — Librarian draft + form review |
|
|
196
|
+
| Skill 트랙 정리 | ⏳ form 결정 보류, 차후 |
|
|
136
197
|
|
|
137
|
-
|
|
198
|
+
---
|
|
138
199
|
|
|
139
|
-
|
|
200
|
+
## 참조 문서
|
|
140
201
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
| OpenAI only | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | OpenAI |
|
|
145
|
-
| Anthropic only | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | Anthropic |
|
|
146
|
-
| Premium | gemini-2.5-flash | gpt-4o-mini | grok-4.20-0309-reasoning | grok-4.20-0309-reasoning | OpenAI + Google + xAI |
|
|
202
|
+
- [`RESPEC.md`](./RESPEC.md) — 현재 vision + 회의 결정사항 + 구현 detail (단일 진실 원천)
|
|
203
|
+
- [`SPEC.md`](./SPEC.md) — 구 SPEC (v0.x 역사 보존, 일부 §3.4 Memory Tier가 본 vision의 원형)
|
|
204
|
+
- [`PROBLEMS.md`](./PROBLEMS.md) — 현재 진행 중 cleanup 단계 / 진단 결과
|
|
147
205
|
|
|
148
|
-
|
|
206
|
+
---
|
|
149
207
|
|
|
150
|
-
##
|
|
208
|
+
## 가이드 원칙
|
|
151
209
|
|
|
152
|
-
|
|
153
|
-
- [x] v0.5 — Provenance Layer (Model/Platform tracking)
|
|
154
|
-
- [x] v0.6 — **Knowledge Evolution**: Tiered Memory + Skill Grounding
|
|
155
|
-
- [x] v4.5 — Skill System closure (Curator + Auditor + Promotion + Injector filtering)
|
|
156
|
-
- [x] v5.0 — Memory Graph + External Knowledge Grounding + Auto Forgetting + memory_restore
|
|
157
|
-
- [x] **Connectors v1**: Notion page ingestion (`connector_sync` MCP tool)
|
|
158
|
-
- [ ] **Connectors v2**: Notion database iteration, GitHub, Drive
|
|
159
|
-
- [ ] v1.0 — **Production Ready**: Full benchmark and stability
|
|
210
|
+
> 눈앞 문제 해결한다고 전체 구조가 망가지면 안 됨.
|
|
160
211
|
|
|
161
|
-
|
|
212
|
+
매 작업/제안 시 RESPEC.md vision 정합 검증 → "이 fix가 큰 틀과 맞나?" 확인 후 진행.
|
|
213
|
+
"일단 돌게만 만들자"는 멈춤 신호.
|
|
162
214
|
|
|
163
|
-
|
|
215
|
+
---
|
|
164
216
|
|
|
165
|
-
|
|
166
|
-
MIT
|
|
217
|
+
*Status: fresh implementation 준비 단계. 실제 구현은 form 결정 후 진행.*
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# mcp-agents-memory (v0.6.0)
|
|
2
|
+
|
|
3
|
+
Multi-agent Shared Long-term Memory MCP Server.
|
|
4
|
+
An MCP server that enables AI agents (Claude, Gemini, GPT, etc.) to **autonomously manage memory** and evolve knowledge into **validated operational rules (Skills)**.
|
|
5
|
+
|
|
6
|
+
## 🌟 New in v0.6: Knowledge Evolution
|
|
7
|
+
|
|
8
|
+
- **🧠 Memory Tiering**: Intelligent loading strategy mimicking human memory. Full detail for the **last 30 days** (short-term) and metadata/important summaries for older records (long-term).
|
|
9
|
+
- **🦾 Skill Evolution**: Repetitive patterns and project know-how automatically evolve into **Skills**. These rules are injected into the agent's system prompt to guide future actions.
|
|
10
|
+
- **🌐 Authority Grounding**: High-value facts are reconciled against external authority sources (**Tavily** for recency, **Exa** for authority/docs) before storage.
|
|
11
|
+
- **⚡ MCP Prompts (Slash Commands)**: Direct interaction via `/briefing`, `/recall <query>`, and `/save <text>` for a premium UX.
|
|
12
|
+
- **🔐 Cross-MCP Ready**: Standardized context hooks to share `subject_key` and `session_id` with other MCPs (Vision, Audio, etc.).
|
|
13
|
+
|
|
14
|
+
## Features
|
|
15
|
+
|
|
16
|
+
- **📚 Librarian Engine**: Multi-model pipeline (Triage → Extract → Audit) for zero-config fact extraction.
|
|
17
|
+
- **⚡ Contradiction Resolution**: Detects and updates conflicting information (e.g., "Lives in Seoul" → "Moved to Busan").
|
|
18
|
+
- **🧠 Smart Briefing**: Dynamic session startup with user profile, project context, and applicable **Skills**.
|
|
19
|
+
- **🔍 Semantic Search**: Vector embedding-based retrieval with automatic tier-up for matching long-term memories.
|
|
20
|
+
- **🔐 Unified Provenance**: Every fact is tagged with `author_model`, `platform`, and `session_id` for perfect traceability.
|
|
21
|
+
|
|
22
|
+
## 🧠 Hybrid Intelligence Tech Stack
|
|
23
|
+
|
|
24
|
+
v0.6 employs a sophisticated multi-role architecture using the best models for each specialized task.
|
|
25
|
+
|
|
26
|
+
| Role | Technology | Description |
|
|
27
|
+
|----------|------------|-------------|
|
|
28
|
+
| **Skill Auditor** | Anthropic `Sonnet` / `Gemini Pro` | **Grounding**: Reconciles facts with external docs using Tavily + Exa. |
|
|
29
|
+
| **Skill Curator** | Google `Gemini Flash` | **Promotion**: Monitors memory clusters to identify skill candidates. |
|
|
30
|
+
| **Fact Extractor** | OpenAI `gpt-4o-mini` | **Extraction**: Efficient atomic fact generation from text. |
|
|
31
|
+
| **Embedding** | OpenAI `text-embedding-3-small` | **Standard**: 1536-dim vector indexing for semantic search. |
|
|
32
|
+
| **Search (Required)** | **Tavily + Exa** | **The Two Pillars**: Tavily (Recency) + Exa (Authority/Research). |
|
|
33
|
+
| **Database** | PostgreSQL + pgvector | **Tiered Storage**: Tier-aware partitioning (Short/Long term). |
|
|
34
|
+
|
|
35
|
+
## Architecture
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
┌─────────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
39
|
+
│ Claude Code │ │ Gemini │ │ GPT │
|
|
40
|
+
│ (Zero-Config) │ │ (Autonomous) │ │ (Autonomous) │
|
|
41
|
+
└────────┬────────┘ └──────┬───────┘ └──────┬───────┘
|
|
42
|
+
│ │ │
|
|
43
|
+
└─────────────────────┼────────────────────┘
|
|
44
|
+
│
|
|
45
|
+
┌──────────▼──────────┐
|
|
46
|
+
│ MCP Protocol │
|
|
47
|
+
│ (w/ instructions) │ ← Zero-Config Entry
|
|
48
|
+
└──────────┬──────────┘
|
|
49
|
+
│
|
|
50
|
+
┌──────────▼──────────┐ ┌──────────────────┐
|
|
51
|
+
│ mcp-agents-memory │ │ Skill Track │
|
|
52
|
+
│ ┌───────────────┐ │ ───▶ │ Curator/Auditor │
|
|
53
|
+
│ │ Librarian │ │ │ (Knowledge/Web) │
|
|
54
|
+
│ │ Engine │ │ └────────┬─────────┘
|
|
55
|
+
│ └───────┬───────┘ │ │
|
|
56
|
+
└──────────┼──────────┘ ┌────────▼─────────┐
|
|
57
|
+
│ │ Skills Table │
|
|
58
|
+
┌──────────▼──────────┐ │ (Operational) │
|
|
59
|
+
│ PostgreSQL + pgvec │ └──────────────────┘
|
|
60
|
+
│ (Tiered Memories) │
|
|
61
|
+
└─────────────────────┘
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Setup
|
|
65
|
+
|
|
66
|
+
### Install
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npm i -g mcp-agents-memory
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Configure
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
mcp-agents-memory setup
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The interactive wizard:
|
|
79
|
+
- Prompts for your Postgres connection (cloud provider with `pgvector` recommended — [Neon](https://neon.tech) and [Supabase](https://supabase.com) both have free tiers; URL must end with `?sslmode=require`).
|
|
80
|
+
- Asks for the required OpenAI key (embeddings).
|
|
81
|
+
- Lets you pick a Librarian model preset (see below).
|
|
82
|
+
- Writes config to `~/.config/mcp-agents-memory/.env`.
|
|
83
|
+
- Applies the base schema and runs all migrations idempotently.
|
|
84
|
+
|
|
85
|
+
### Add to your MCP client
|
|
86
|
+
|
|
87
|
+
Claude Desktop / Claude Code / any MCP-aware client:
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"mcpServers": {
|
|
92
|
+
"memory": {
|
|
93
|
+
"command": "mcp-agents-memory",
|
|
94
|
+
"env": {
|
|
95
|
+
"AGENT_KEY": "agent_claude",
|
|
96
|
+
"AGENT_PLATFORM": "claude-code"
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`AGENT_PLATFORM` is recorded as the Curator's harness identity on every memory_add call. The Curator's model is captured per-call (defaulting to the Producer's author_model) — set explicitly via the curator_model argument when an orchestrator saves memories on behalf of a different model (e.g. delegating to a subagent). This avoids the staleness that env-static model values would introduce when /model swaps mid-session.
|
|
104
|
+
|
|
105
|
+
`agent_key` (optional): Agent persona key for multi-persona harnesses (OpenClaw, Hermes, Opencode). Single-persona setups can ignore — `AGENT_KEY` env is the default. Applies to `memory_add`, `memory_save_skill`, and `memory_curator_run`.
|
|
106
|
+
|
|
107
|
+
### Cross-machine memory
|
|
108
|
+
|
|
109
|
+
On a second computer, run `npm i -g mcp-agents-memory` and `mcp-agents-memory setup` pointing to the **same** `DATABASE_URL`. Memory shares automatically — the database is the source of truth and the MCP server is stateless.
|
|
110
|
+
|
|
111
|
+
### CLI
|
|
112
|
+
|
|
113
|
+
- `mcp-agents-memory` — run the MCP server (stdio).
|
|
114
|
+
- `mcp-agents-memory setup` — interactive wizard (writes XDG config, applies schema + migrations).
|
|
115
|
+
- `mcp-agents-memory migrate` — apply pending migrations against an already-configured database.
|
|
116
|
+
- `mcp-agents-memory help` — show help.
|
|
117
|
+
|
|
118
|
+
### Local development
|
|
119
|
+
|
|
120
|
+
For self-hosted Postgres or working on the codebase directly:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
git clone https://github.com/a3lab01create-bit/mcp-agents-memory.git
|
|
124
|
+
cd mcp-agents-memory
|
|
125
|
+
npm install
|
|
126
|
+
npm run build
|
|
127
|
+
npm run setup
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Config search order: `$MEMORY_CONFIG_PATH` → `./.env` → `~/.config/mcp-agents-memory/.env` → `<package>/.env`. Project-root `.env` wins for dev workflows.
|
|
131
|
+
|
|
132
|
+
### Requirements
|
|
133
|
+
- PostgreSQL ≥ 14 with the `pgvector` extension.
|
|
134
|
+
- **Required API key**: OpenAI (embeddings).
|
|
135
|
+
- **Optional API keys**: depends on the wizard preset you pick (see below).
|
|
136
|
+
|
|
137
|
+
### Model presets
|
|
138
|
+
|
|
139
|
+
The wizard offers four presets for the always-on Librarian roles. Every role still accepts `<ROLE>_PROVIDER` and `<ROLE>_MODEL` env overrides if you want to mix and match.
|
|
140
|
+
|
|
141
|
+
| Preset | Triage | Extract | Audit | Contradiction | Required keys |
|
|
142
|
+
|---|---|---|---|---|---|
|
|
143
|
+
| **Recommended** | gemini-2.5-flash-lite | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | OpenAI + Google |
|
|
144
|
+
| OpenAI only | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | OpenAI |
|
|
145
|
+
| Anthropic only | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | Anthropic |
|
|
146
|
+
| Premium | gemini-2.5-flash | gpt-4o-mini | grok-4.20-0309-reasoning | grok-4.20-0309-reasoning | OpenAI + Google + xAI |
|
|
147
|
+
|
|
148
|
+
Grounding roles (`skill_auditor` + `memory_auditor`) default to `claude-sonnet-4-6` and only fire when `PROMOTION_ENABLED` / `MEMORY_AUDIT_ENABLED` are on. Sonnet calls use prompt caching automatically — repeat audits within 5 minutes hit at ~10× cheaper rate.
|
|
149
|
+
|
|
150
|
+
## Roadmap
|
|
151
|
+
|
|
152
|
+
- [x] v0.4 — Librarian Engine (Auto extraction + resolution)
|
|
153
|
+
- [x] v0.5 — Provenance Layer (Model/Platform tracking)
|
|
154
|
+
- [x] v0.6 — **Knowledge Evolution**: Tiered Memory + Skill Grounding
|
|
155
|
+
- [x] v4.5 — Skill System closure (Curator + Auditor + Promotion + Injector filtering)
|
|
156
|
+
- [x] v5.0 — Memory Graph + External Knowledge Grounding + Auto Forgetting + memory_restore
|
|
157
|
+
- [x] **Connectors v1**: Notion page ingestion (`connector_sync` MCP tool)
|
|
158
|
+
- [ ] **Connectors v2**: Notion database iteration, GitHub, Drive
|
|
159
|
+
- [ ] v1.0 — **Production Ready**: Full benchmark and stability
|
|
160
|
+
|
|
161
|
+
## Credits
|
|
162
|
+
|
|
163
|
+
Built by **Hoon** ([triplealab](https://github.com/a3lab01create-bit)) in collaboration with **Claude** (Anthropic) and **Codex** (OpenAI). Most of v0.5 / v0.6 / v4.5 / v5.0 was designed and implemented through iterative human-AI pair programming — eating our own dog food on the same memory and skill systems this server provides.
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
MIT
|