mcp-agents-memory 0.6.0

package/.env.example

@@ -0,0 +1,109 @@
+# ─────────────────────────────────────────────────────────────
+# mcp-agents-memory — example configuration
+# ─────────────────────────────────────────────────────────────
+# Loaded by db.ts in this order (first hit wins):
+#   1. $MEMORY_CONFIG_PATH        (explicit override)
+#   2. ./.env                     (project-local — dev workflow)
+#   3. ~/.config/mcp-agents-memory/.env   (XDG — what `setup` writes)
+#   4. <package>/../.env          (legacy fallback)
+
+# ─────────────────────────────────────────────────────────────
+# Database — choose ONE path
+# ─────────────────────────────────────────────────────────────
+
+# (a) Connection string (recommended for cloud Postgres — Neon, Supabase, etc.)
+# Append `?sslmode=require` for any cloud provider — pg won't auto-enable SSL otherwise.
+# DATABASE_URL=postgres://user:pass@host:5432/db?sslmode=require
+
+# (b) Individual fields (legacy / self-hosted local)
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASS=password
+DB_NAME=mcp_memory
+# DB_SSL=true   # set true for SSL when using individual fields
+
+# SSH Tunneling (Optional — only for reaching a Postgres behind SSH bastion)
+SSH_ENABLED=false
+SSH_HOST=
+SSH_PORT=22
+SSH_USER=
+SSH_KEY_PATH=
+
+# ─────────────────────────────────────────────────────────────
+# AI keys
+# ─────────────────────────────────────────────────────────────
+
+# OpenAI (Required — embeddings + Librarian fact extraction)
+# Get your key at: https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-...
+
+# Optional — needed only for the preset / role you choose below.
+# ANTHROPIC_API_KEY=                       # required if any role uses provider=anthropic
+# GOOGLE_GENERATIVE_AI_API_KEY=            # required if any role uses provider=google
+# GROK_API_KEY=                            # required if any role uses provider=xai
+# TAVILY_API_KEY=                          # only when MEMORY_AUDIT_ENABLED or PROMOTION_ENABLED is on
+# EXA_API_KEY=                             # only when MEMORY_AUDIT_ENABLED or PROMOTION_ENABLED is on
+
+# Optional — Notion Connector (v5.0 Phase 3). Required to use connector_sync(provider='notion').
+# Create an integration at https://www.notion.so/profile/integrations and share pages with it.
+# NOTION_API_KEY=
+
+# ─────────────────────────────────────────────────────────────
+# LLM role assignments — every role accepts <ROLE>_PROVIDER + <ROLE>_MODEL.
+# Defaults below match the wizard's "Recommended" preset.
+#
+# Three other presets are available via the wizard (no manual overriding needed):
+#   - OpenAI only: every role on gpt-4o-mini (only OPENAI_API_KEY needed)
+#   - Anthropic only: every role on claude-haiku-4-5 (only ANTHROPIC_API_KEY)
+#   - Premium: audit + contradiction switched to grok-4.20-0309-reasoning
+# ─────────────────────────────────────────────────────────────
+
+EMBEDDING_MODEL=text-embedding-3-small
+
+TRIAGE_PROVIDER=google
+TRIAGE_MODEL=gemini-2.5-flash-lite
+
+EXTRACT_PROVIDER=openai
+EXTRACT_MODEL=gpt-4o-mini
+
+AUDIT_PROVIDER=openai
+AUDIT_MODEL=gpt-4o-mini
+
+CONTRADICTION_PROVIDER=openai
+CONTRADICTION_MODEL=gpt-4o-mini
+
+SKILL_CURATOR_PROVIDER=openai
+SKILL_CURATOR_MODEL=gpt-4o-mini
+
+# Grounding roles — only fire when their gate is on.
+SKILL_AUDITOR_PROVIDER=anthropic
+SKILL_AUDITOR_MODEL=claude-sonnet-4-6
+
+MEMORY_AUDITOR_PROVIDER=anthropic
+MEMORY_AUDITOR_MODEL=claude-sonnet-4-6
+
+# Optional default subject key for `memory_startup` if the caller doesn't pass one.
+# MEMORY_DEFAULT_SUBJECT=user_yourname
+
+# ─────────────────────────────────────────────────────────────
+# Optional v4.5 / v5.0 background loops — opt-in
+# ─────────────────────────────────────────────────────────────
+
+# Skill Promotion Engine (background auto-curator)
+PROMOTION_ENABLED=false
+PROMOTION_INTERVAL_MIN=60
+PROMOTION_WARMUP_MIN=5
+
+# Memory Auditor (v5.0 SYNC external knowledge grounding)
+# Gate: MEMORY_AUDIT_ENABLED=true AND fact_type='learning' AND importance > 7.
+MEMORY_AUDIT_ENABLED=false
+MEMORY_AUDITOR_MODEL=claude-sonnet-4-6
+
+# Auto Forgetting (v5.0 Phase 3)
+# Soft-deletes low-score memories on a background interval.
+# Profile facts and validation_status='pending' rows are immune.
+FORGETTING_ENABLED=false
+FORGETTING_WARMUP_MIN=30
+FORGETTING_INTERVAL_MIN=1440
+FORGET_THRESHOLD=0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hoon (triplealab)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# mcp-agents-memory (v0.6.0)
+
+Multi-agent Shared Long-term Memory MCP Server.  
+An MCP server that enables AI agents (Claude, Gemini, GPT, etc.) to **autonomously manage memory** and evolve knowledge into **validated operational rules (Skills)**.
+
+## 🌟 New in v0.6: Knowledge Evolution
+
+- **🧠 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).
+- **🦾 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.
+- **🌐 Authority Grounding**: High-value facts are reconciled against external authority sources (**Tavily** for recency, **Exa** for authority/docs) before storage.
+- **⚡ MCP Prompts (Slash Commands)**: Direct interaction via `/briefing`, `/recall <query>`, and `/save <text>` for a premium UX.
+- **🔐 Cross-MCP Ready**: Standardized context hooks to share `subject_key` and `session_id` with other MCPs (Vision, Audio, etc.).
+
+## Features
+
+- **📚 Librarian Engine**: Multi-model pipeline (Triage → Extract → Audit) for zero-config fact extraction.
+- **⚡ Contradiction Resolution**: Detects and updates conflicting information (e.g., "Lives in Seoul" → "Moved to Busan").
+- **🧠 Smart Briefing**: Dynamic session startup with user profile, project context, and applicable **Skills**.
+- **🔍 Semantic Search**: Vector embedding-based retrieval with automatic tier-up for matching long-term memories.
+- **🔐 Unified Provenance**: Every fact is tagged with `author_model`, `platform`, and `session_id` for perfect traceability.
+
+## 🧠 Hybrid Intelligence Tech Stack
+
+v0.6 employs a sophisticated multi-role architecture using the best models for each specialized task.
+
+| Role | Technology | Description |
+|----------|------------|-------------|
+| **Skill Auditor** | Anthropic `Sonnet` / `Gemini Pro` | **Grounding**: Reconciles facts with external docs using Tavily + Exa. |
+| **Skill Curator** | Google `Gemini Flash` | **Promotion**: Monitors memory clusters to identify skill candidates. |
+| **Fact Extractor** | OpenAI `gpt-4o-mini` | **Extraction**: Efficient atomic fact generation from text. |
+| **Embedding** | OpenAI `text-embedding-3-small` | **Standard**: 1536-dim vector indexing for semantic search. |
+| **Search (Required)** | **Tavily + Exa** | **The Two Pillars**: Tavily (Recency) + Exa (Authority/Research). |
+| **Database** | PostgreSQL + pgvector | **Tiered Storage**: Tier-aware partitioning (Short/Long term). |
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────┐     ┌──────────────┐
+│   Claude Code   │     │   Gemini     │     │     GPT      │
+│ (Zero-Config)   │     │ (Autonomous) │     │ (Autonomous) │
+└────────┬────────┘     └──────┬───────┘     └──────┬───────┘
+         │                     │                    │
+         └─────────────────────┼────────────────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │   MCP Protocol      │
+                    │ (w/ instructions)   │  ← Zero-Config Entry
+                    └──────────┬──────────┘
+                               │
+                    ┌──────────▼──────────┐      ┌──────────────────┐
+                    │  mcp-agents-memory  │      │  Skill Track     │
+                    │  ┌───────────────┐  │ ───▶ │  Curator/Auditor │
+                    │  │   Librarian   │  │      │  (Knowledge/Web) │
+                    │  │   Engine      │  │      └────────┬─────────┘
+                    │  └───────┬───────┘  │               │
+                    └──────────┼──────────┘      ┌────────▼─────────┐
+                               │                 │   Skills Table   │
+                    ┌──────────▼──────────┐      │ (Operational)    │
+                    │  PostgreSQL + pgvec │      └──────────────────┘
+                    │  (Tiered Memories)  │
+                    └─────────────────────┘
+```
+
+## Setup
+
+### Install
+
+```bash
+npm i -g mcp-agents-memory
+```
+
+### Configure
+
+```bash
+mcp-agents-memory setup
+```
+
+The interactive wizard:
+- 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`).
+- Asks for the required OpenAI key (embeddings).
+- Lets you pick a Librarian model preset (see below).
+- Writes config to `~/.config/mcp-agents-memory/.env`.
+- Applies the base schema and runs all migrations idempotently.
+
+### Add to your MCP client
+
+Claude Desktop / Claude Code / any MCP-aware client:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "mcp-agents-memory"
+    }
+  }
+}
+```
+
+### Cross-machine memory
+
+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.
+
+### CLI
+
+- `mcp-agents-memory` — run the MCP server (stdio).
+- `mcp-agents-memory setup` — interactive wizard (writes XDG config, applies schema + migrations).
+- `mcp-agents-memory migrate` — apply pending migrations against an already-configured database.
+- `mcp-agents-memory help` — show help.
+
+### Local development
+
+For self-hosted Postgres or working on the codebase directly:
+
+```bash
+git clone https://github.com/a3lab01create-bit/mcp-agents-memory.git
+cd mcp-agents-memory
+npm install
+npm run build
+npm run setup
+```
+
+Config search order: `$MEMORY_CONFIG_PATH` → `./.env` → `~/.config/mcp-agents-memory/.env` → `<package>/.env`. Project-root `.env` wins for dev workflows.
+
+### Requirements
+- PostgreSQL ≥ 14 with the `pgvector` extension.
+- **Required API key**: OpenAI (embeddings).
+- **Optional API keys**: depends on the wizard preset you pick (see below).
+
+### Model presets
+
+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.
+
+| Preset | Triage | Extract | Audit | Contradiction | Required keys |
+|---|---|---|---|---|---|
+| **Recommended** | gemini-2.5-flash-lite | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | OpenAI + Google |
+| OpenAI only | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | OpenAI |
+| Anthropic only | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | Anthropic |
+| Premium | gemini-2.5-flash | gpt-4o-mini | grok-4.20-0309-reasoning | grok-4.20-0309-reasoning | OpenAI + Google + xAI |
+
+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.
+
+## Roadmap
+
+- [x] v0.4 — Librarian Engine (Auto extraction + resolution)
+- [x] v0.5 — Provenance Layer (Model/Platform tracking)
+- [x] v0.6 — **Knowledge Evolution**: Tiered Memory + Skill Grounding
+- [x] v4.5 — Skill System closure (Curator + Auditor + Promotion + Injector filtering)
+- [x] v5.0 — Memory Graph + External Knowledge Grounding + Auto Forgetting + memory_restore
+- [x] **Connectors v1**: Notion page ingestion (`connector_sync` MCP tool)
+- [ ] **Connectors v2**: Notion database iteration, GitHub, Drive
+- [ ] v1.0 — **Production Ready**: Full benchmark and stability
+
+## Credits
+
+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.
+
+## License
+MIT

package/README_KR.md

@@ -0,0 +1,113 @@
+# mcp-agents-memory (v0.6.0)
+
+멀티 에이전트 공유 장기 기억 MCP 서버.  
+AI 에이전트(Claude, Gemini, GPT 등)가 별도의 설정 없이도 **자율적으로 기억을 관리**하고, 지능적인 검증을 통해 신뢰할 수 있는 지식 베이스를 구축하게 해주는 MCP 서버입니다.
+
+## 🌟 v0.6 신규 기능: 유니버설 자율성 (Universal Autonomy)
+
+- **🧠 Zero-Config 자율성**: 더 이상 `settings.json`에 복잡한 hooks를 설정할 필요가 없습니다! 서버가 MCP `instructions` 필드를 통해 에이전트에게 직접 지침을 내려, 에이전트가 스스로 메모리 도구를 사용하도록 유도합니다.
+- **⚖️ 선별적 감사 (Selective Audit)**: 추출된 모든 사실 중 중요도가 높은 상위 5개의 사실만 골라 고성능 모델(Opus/Grok)에게 정밀 검증을 맡깁니다. 비용은 아끼고 품질은 높였습니다.
+- **🌐 출처 가중치 (Source Weighting)**: 외부 사실 검증 시 도메인 권위(.gov, .edu, 공식 문서 등)에 따라 가중치를 부여합니다. 공신력 있는 정보를 우선적으로 신뢰합니다.
+- **⚡ MCP Prompts (슬래시 명령어)**: `/briefing`, `/recall <query>`, `/save <text>`와 같은 직관적인 명령어로 메모리와 직접 상호작용할 수 있습니다.
+- **🔐 통합 출처 관리**: 모든 기억에 출처 모델(`author_model`), 플랫폼(`platform`), 세션 ID가 자동으로 기록되어 완벽한 추적성을 보장합니다.
+
+## 주요 기능
+
+- **📚 Librarian AI**: 대화 원문을 자동으로 분석 → 핵심 사실(fact) 추출, 분류, 저장
+- **⚡ 모순 해결(Contradiction Resolution)**: "서울 거주" → "부산 이사" 같은 모순을 자동 감지하고 기존 기억을 업데이트(Supersede)합니다.
+- **🧠 스마트 브리핑**: 세션 시작 시 유저 프로필, 프로젝트 상태, 핵심 결정사항을 한 번에 브리핑합니다.
+- **🔍 시맨틱 검색**: 벡터 임베딩 기반 검색 + 유저 프로필 자동 첨부 기능을 지원합니다.
+- **🔐 SSH 터널링**: 원격 DB에 안전하게 접속하며, 안정적인 연결 관리 기능을 제공합니다.
+- **🤖 멀티 에이전트**: 어떤 AI 모델이나 플랫폼을 사용하더라도 동일한 메모리 풀을 공유합니다.
+
+## 🧠 하이브리드 지능 기술 스택 (Hybrid Intelligence)
+
+v0.6은 대량의 데이터 처리는 효율적인 모델이, 핵심적인 추론과 검증은 최고급 모델이 담당하는 **지능형 멀티 모델 아키텍처**를 채택하고 있습니다.
+
+| 역할 | 기술 | 설명 |
+|----------|------------|-------------|
+| **메인 브레인** | Anthropic `Claude 3 Opus` | **선별적 감사(Selective Audit)**: 고가치 사실 및 결정 사항 정밀 검증. |
+| **진실 추론기** | xAI `Grok-1` | **검증 통합(Validation Synthesis)**: 외부 웹 데이터를 기반으로 사실성 판단. |
+| **사실 추출기** | OpenAI `gpt-4o-mini` | **Librarian 엔진**: 빠르고 비용 효율적인 데이터 추출 및 분류. |
+| **임베딩** | OpenAI `text-embedding-3-small` | **시맨틱 검색**: 표준화된 1536차원 벡터 인덱싱. |
+| **검색 엔진** | Tavily + Exa | **가중치 기반 검색**: 도메인 권위(gov, edu)를 고려한 외부 근거 확보. |
+| **데이터베이스** | PostgreSQL + pgvector | **벡터 저장소**: 확장 가능한 장기 기억 저장소. |
+
+## 설치 및 설정
+
+### 1. 설치 및 빌드
+
+```bash
+npm install
+npm run build
+```
+
+### 2. 설정 위저드 실행
+
+```bash
+npm run setup
+```
+
+DB 연결, SSH 터널, OpenAI API 키를 설정하고 스키마를 자동 생성합니다.
+
+### 3. 모든 MCP 클라이언트에 연결
+클라이언트(Claude Code, Antigravity 등)에 서버를 추가하기만 하면 됩니다. 별도의 훅 설정은 필요하지 않습니다!
+```bash
+claude mcp add mcp-agents-memory node /path/to/build/index.js
+```
+
+## 도구 및 프롬프트 (v0.6)
+
+### 🚨 Prompts (슬래시 명령어)
+- `/briefing`: 현재 세션의 전체 브리핑을 요청합니다.
+- `/recall <query>`: 메모리에서 관련 정보를 빠르게 검색합니다.
+- `/save <text>`: 특정 사실이나 결정사항을 수동으로 저장합니다.
+
+### 🛠️ 핵심 도구
+- `memory_startup`: 유저 프로필 및 프로젝트 상태를 로드합니다.
+- `memory_add`: 자동 출처 기록 및 감사가 포함된 사실 추출을 수행합니다.
+- `memory_search`: 통합 시맨틱 + 키워드 검색을 수행합니다.
+- `memory_status`: 시스템 상태 및 메모리 통계를 확인합니다.
+
+## 아키텍처
+
+```
+┌─────────────────┐     ┌──────────────┐     ┌──────────────┐
+│   Claude Code   │     │   Gemini     │     │     GPT      │
+│ (Zero-Config)   │     │  (자율 작동)  │     │  (자율 작동)  │
+└────────┬────────┘     └──────┬───────┘     └──────┬───────┘
+         │                     │                     │
+         └─────────────────────┼─────────────────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │   MCP Protocol      │
+                    │ (w/ instructions)   │  ← v0.6 신규
+                    └──────────┬──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │  mcp-agents-memory  │
+                    │  ┌───────────────┐  │
+                    │  │  Selective    │  │  ← 상위 5개 랭커
+                    │  │  Audit        │  │
+                    │  └───────┬───────┘  │
+                    └──────────┼──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │  PostgreSQL + pgvec │
+                    │  (통합 Facts 테이블)  │  ← v0.6 메타데이터 포함
+                    └─────────────────────┘
+```
+
+## 로드맵
+
+- [x] v0.1 — 기본 CRUD 메모리 시스템
+- [x] v0.2 — 동적 주체 생성, pgvector 시맨틱 검색
+- [x] v0.3 — 스마트 브리핑, 원자적 저장 강제
+- [x] v0.4 — Librarian 엔진 (자동 추출 및 해결)
+- [x] v0.5 — 출처 관리 레이어 (모델/플랫폼 신뢰도)
+- [x] v0.6 — **유니버설 자율성**: Zero-Config + 선별적 감사 ← **현재**
+- [ ] v0.8 — **메모리 그래프**: 지식 그래프 연관 추론 및 자동 만료
+- [ ] v1.0 — **프로덕션 준비**: npm 배포 및 벤치마킹
+
+## 라이선스
+MIT