memento-mcp-server 0.1.0

package/docker-compose.prod.yml

@@ -0,0 +1,77 @@
+version: '3.8'
+
+services:
+  memento-prod:
+    build: 
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8080:8080"
+    environment:
+      - NODE_ENV=production
+      - DOCKER=true
+      - DB_PATH=/app/data/memory.db
+      - LOG_LEVEL=info
+      - PORT=8080
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+      - EMBEDDING_PROVIDER=${EMBEDDING_PROVIDER:-lightweight}
+      - GEMINI_MODEL=${GEMINI_MODEL:-text-embedding-004}
+      - EMBEDDING_DIMENSIONS=${EMBEDDING_DIMENSIONS:-512}
+      - MAX_CONNECTIONS=${MAX_CONNECTIONS:-1000}
+      - CACHE_TTL=${CACHE_TTL:-300000}
+      - CACHE_MAX_SIZE=${CACHE_MAX_SIZE:-1000}
+    volumes:
+      - ./data:/app/data
+      - ./logs:/app/logs
+    restart: unless-stopped
+    command: ["/app/start-container.sh"]
+    stdin_open: true
+    tty: true
+    networks:
+      - memento-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # 프로덕션용 Redis (캐싱)
+  redis-prod:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_prod_data:/data
+    restart: unless-stopped
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    networks:
+      - memento-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  # Nginx 리버스 프록시 (선택사항)
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./ssl:/etc/nginx/ssl:ro
+    depends_on:
+      - memento-prod
+    restart: unless-stopped
+    networks:
+      - memento-network
+
+volumes:
+  redis_prod_data:
+
+networks:
+  memento-network:
+    driver: bridge

package/docker-compose.yml

@@ -0,0 +1,43 @@
+services:
+  memento-mcp-server:
+    build: .
+    ports:
+      - "9001:9001"
+    environment:
+      - NODE_ENV=production
+      - DOCKER=true
+      - DB_PATH=/app/data/memory.db
+      - LOG_LEVEL=info
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+      - EMBEDDING_PROVIDER=${EMBEDDING_PROVIDER:-lightweight}
+      - GEMINI_MODEL=${GEMINI_MODEL:-text-embedding-004}
+      - EMBEDDING_DIMENSIONS=${EMBEDDING_DIMENSIONS:-512}
+      - PORT=9001
+    volumes:
+      - ./data:/app/data
+      - ./logs:/app/logs
+    restart: unless-stopped
+    user: root
+    command: ["/app/start-container.sh"]
+    stdin_open: true
+    tty: true
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9001/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # Redis for caching (optional)
+  # redis:
+  #   image: redis:7-alpine
+  #   ports:
+  #     - "6379:6379"
+  #   volumes:
+  #     - redis_data:/data
+  #   restart: unless-stopped
+  #   command: redis-server --appendonly yes
+
+volumes:
+  redis_data:

package/docs/en/Memento-Goals.md

@@ -0,0 +1,217 @@
+# Memento Goals
+
+## 1. Goal Summary
+
+**Goal**: Provide storage+search+summary+forgetting mechanisms modeled after human memory systems (working memory, episodic memory, semantic memory, procedural memory) so that agents don't lose conversation/task context.
+
+**Non-goals**: Large-scale RAG platforms, general-purpose data lakes. Initially focus on personal/workspace-level long-term memory and conversation-session transitions.
+
+### Rationale for Human Memory Model
+
+- **Episodic/Semantic Separation**: Tulving lineage – episodic is events, semantic is knowledge. The two systems are interdependent. [PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2657600/) +1
+
+- **Working Memory**: Central executive, phonological loop, visuospatial memory components manage "currently processing information". [Simply Psychology](https://www.simplypsychology.org/working-memory.html) +1
+
+- **Forgetting/Spaced Repetition**: Ebbinghaus curve and "periodic reminders" are advantageous for long-term retention. [PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2657600/) +1
+
+### MCP Application Rationale
+
+MCP exposes Tools/Resources/Prompts as standards and can be easily connected from clients (Claude, ChatGPT, Cursor, etc.). [WorkOS](https://workos.com/) +3, [Model Context Protocol](https://modelcontextprotocol.io/) +3
+
+## 2. System Overview (Components)
+
+### Memory MCP Server
+
+- **Protocol**: MCP (spec 2025-03-26)
+- **Interface**: tools (memory write/search/pin/delete, etc.), resources (read-only views), prompts (context injection templates). [Model Context Protocol](https://modelcontextprotocol.io/) +1
+
+### Storage
+
+- **Primary**: PostgreSQL + pgvector (managing vectors/metadata/transactions together). [GitHub](https://github.com/pgvector/pgvector) +1
+- **Alternative**: SQLite+FTS5 (+lancedb) for embedded, or Qdrant/Milvus for separation
+
+### Embedding & Summary
+
+Text embedding models (sentence embeddings), "information compression summarizer (map-reduce)" pipeline.
+
+### Scheduler/Worker
+
+"Sleep consolidation" batch (nighttime clustering, summarization, rule extraction), "forgetting/review" batch (re-exposure, deletion candidate selection).
+
+## 3. Data Model (Corresponding to Human Memory)
+
+### Core Tables
+
+#### memory_item
+- `id`, `type`(working|episodic|semantic|procedural), `title`, `content`, `source`(chat|tool|file|url), `agent_id`, `user_id`, `project_id`
+- `created_at`, `last_accessed_at`, `importance`(0~1), `pinned`(bool), `privacy_scope`(private|team|public), `origin_trace`(json)
+
+#### memory_embedding
+- `memory_id` FK, `embedding` vector, `dim`
+
+#### memory_tag (N:N)
+- Tags (e.g., tech:mariadb, pref:coffee, task:ads-settlement)
+
+#### memory_link
+- Relationships between memories (cause_of, derived_from, duplicates, contradicts) – semantic connection network
+
+#### feedback_event
+- `memory_id`, `event`(used|edited|neglected|helpful|not_helpful), `score`, `ts`
+
+### Working Memory Buffer
+
+#### wm_buffer
+- `session_id`, `items`(json), `token_budget`, `expires_at`
+
+When session ends/token limit exceeded, transition to **episodic** snapshot.
+
+## 4. Search, Ranking, Forgetting (Including Formulas)
+
+### 4.1 Search Score
+
+Final score S:
+
+```
+S = α * relevance + β * recency + γ * importance + δ * usage - ε * duplication_penalty
+```
+
+- **relevance**: Cosine similarity (embedding) + keyword TF-IDF correction
+- **recency**: `exp(-λ * age_days)` (applying Ebbinghaus-type forgetting function; λ is domain-specific tuning) [PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2657600/) +1
+- **importance**: Explicit/inferred ("user preferences, rules, long-term goals" get higher weights)
+- **usage**: Log scale of query/citation/reuse frequency
+- **duplication_penalty**: Deduction for similar items within clusters
+
+### 4.2 Forgetting/Spaced Repetition
+
+- **Soft deletion candidate queue**: Items with low S and old `last_accessed_at` among non-pinned/non-policy items
+- **Retention policy**: Tag/scope-specific TTL (e.g., wm: 48h, episodic: 90d, semantic: indefinite)
+- **Spaced repetition**: High-importance items generate review events (card-form reminders) for re-exposure
+
+### 4.3 Semantic Integration ("Sleep Consolidation")
+
+Cluster recent episodic → conflict/consistency check → generate semantic in rule/fact form
+
+Implement "fast episodic → slow semantic integration" using CLS hypothesis (hippocampus-neocortex complementary learning) as motif. [PubMed](https://pubmed.ncbi.nlm.nih.gov/) +1
+
+## 5. MCP Interface Design (Tools/Resources/Prompts)
+
+### 5.1 tools (Summarized Signatures)
+
+#### remember
+- **Input**: `content`, `type?`, `tags?`, `importance?`, `source?`, `privacy_scope?`
+- **Output**: `memory_id`
+
+#### recall
+- **Input**: `query`, `filters?`(type/tags/time/project/agent), `limit?`
+- **Output**: `items[]`(snippet, score, recall_reason)
+
+#### pin / unpin
+
+#### forget
+- Hard/soft deletion options, GDPR-style "right to erasure" support
+
+#### summarize_thread
+- Current session log → wm_buffer summary → episodic storage
+
+#### link
+- Create relationships between memories (cause, derivation, duplication, contradiction)
+
+#### export
+- NDJSON/Markdown/CSV export
+
+#### feedback
+- Collect usability/accuracy feedback (helpful, not_helpful, attach correct answers)
+
+**MCP Spec Rationale**: Standardize tools/resources/prompts so clients can automatically discover, call, and configure. [Model Context Protocol](https://modelcontextprotocol.io/) +1
+
+### 5.2 resources
+
+- `memory/{id}`: Read-only single view
+- `memory/search?query=...`: Recent search result cache resource (useful for client-side preview)
+
+### 5.3 prompts
+
+#### memory_injection
+- **Description**: "Before this turn's response, inject 'top 5 related memory summaries' as context"
+- **Parameters**: `query`, `token_budget`
+
+Easy for agents to use with MCP Prompts functionality. [Model Context Protocol](https://modelcontextprotocol.io/)
+
+## 6. Agent Execution Flow
+
+1. **WM Loading**: Organize current user message + previous n-turn summary in `wm_buffer`
+2. **Query Construction**: `query = user_msg + task + wm_summary`
+3. **recall call**:
+   - Filter: `project_id`, `tags`, `type in {semantic, episodic}`
+   - 1st ANN (vector) → 2nd rerank (BM25/keyword + rule match)
+   - Deduplication & compression: map-reduce summary, record conflicts as `link(contradicts)`
+4. **Prompt Injection**: Inject top K items with `prompts.memory_injection`
+5. **After Response Generation**:
+   - Record new facts/preferences/decisions with `remember`
+   - Reflect `feedback(helpful)` signals
+6. **Batch Work (Night)**: Clustering, summary integration, forgetting/reminder scheduling
+
+## 7. Minimum Viable Product (MVP) Spec
+
+- Memory write/read/search/pin/delete tools
+- Initially support only episodic/semantic types (working memory as session cache)
+- **Score**: `S = 0.5*relevance + 0.2*recency + 0.2*importance + 0.1*usage`
+- **Retention**: episodic 90d, semantic indefinite, wm 48h
+- **Storage**: Postgres+pgvector, ivfflat index, cosine distance. [GitHub](https://github.com/pgvector/pgvector) +1
+- MCP `prompts.memory_injection` 1 type
+
+## 8. Example: TypeScript MCP Server Skeleton
+
+```typescript
+// package: mcp-memory-server
+import { Server } from "@modelcontextprotocol/sdk/server";
+import { z } from "zod";
+import { recall, remember, pin, unpin, forget, summarizeThread, link, exportMem, feedback } from "./tools";
+
+const server = new Server({ name: "mcp-memory", version: "0.1.0" });
+
+// Tools
+server.tool("remember", {
+  schema: z.object({
+    content: z.string(),
+    type: z.enum(["episodic","semantic"]).default("episodic"),
+    tags: z.array(z.string()).optional(),
+    importance: z.number().min(0).max(1).default(0.5),
+    source: z.string().optional(),
+    privacy_scope: z.enum(["private","team","public"]).default("private")
+  }),
+  handler: remember
+});
+
+server.tool("recall", {
+  schema: z.object({
+    query: z.string(),
+    filters: z.object({
+      type: z.array(z.enum(["episodic","semantic"])).optional(),
+      tags: z.array(z.string()).optional(),
+      project_id: z.string().optional(),
+      time_from: z.string().optional(),
+      time_to: z.string().optional()
+    }).optional(),
+    limit: z.number().default(8)
+  }),
+  handler: recall
+});
+
+// ... register pin/unpin/forget/summarizeThread/link/export/feedback ...
+
+// Resources
+server.resource("memory/{id}", async (params) => {/* read-only view */});
+
+// Prompts
+server.prompt("memory_injection", {
+  params: [{ name: "query", required: true }, { name: "token_budget", required: false }],
+  getPrompt: async ({ query, token_budget = 1200 }) => {
+    const items = await recall({ query, limit: 6 });
+    const summary = await compress(items, token_budget);
+    return [{ role: "system", content: `Related long-term memory summary:\n${summary}` }];
+  }
+});
+
+server.start();
+```

package/docs/en/Memento-M1-DetailSpecs.md

@@ -0,0 +1,130 @@
+# MCP Memory Server M1 Detailed Design Document
+
+## 1. Purpose
+
+This stage (M1) aims to implement a lightweight memory assistant MCP server that can be easily run by individual users in a local environment.
+The database uses SQLite embedded DB that can be used without separate installation, and provides basic functions such as memory storage, search, deletion, and pinning through the MCP interface.
+
+## 2. Overall Architecture
+
+- **Client**: IDE supporting MCP (e.g., Cursor) or AI Agent
+- **Server**: MCP Memory Server (Node.js/TypeScript based)
+- **Storage**: SQLite database (memory.db file)
+
+**Structure**:
+```
+[Client/Agent] ↔ [MCP Memory Server] ↔ [SQLite DB (memory.db)]
+```
+
+## 3. Feature Scope
+
+### Memory Storage (remember)
+- **Input**: content, type, tags, importance, privacy_scope
+- **Output**: memory_id
+- **Action**: Store text in DB, generate embedding and record in vector column
+
+### Memory Search (recall)
+- **Input**: query, filters(type, tags, date), limit
+- **Output**: List of related memories
+- **Action**: Combine FTS5 (keyword) + VSS (vector search)
+
+### Memory Deletion (forget)
+- **Soft Delete**: Automatically removed when TTL expires
+- **Hard Delete**: Direct user call
+
+### Memory Pin/Unpin (pin/unpin)
+- Exclude specific memories from TTL and forgetting policies
+
+## 4. Database Design (SQLite)
+
+### 4.1 Main Table
+
+```sql
+CREATE TABLE memory_item (
+  id TEXT PRIMARY KEY,
+  type TEXT CHECK (type IN ('working','episodic','semantic','procedural')),
+  content TEXT,
+  importance REAL,
+  privacy_scope TEXT CHECK (privacy_scope IN ('private','team','public')) DEFAULT 'private',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  last_accessed TIMESTAMP,
+  pinned BOOLEAN DEFAULT FALSE
+);
+```
+
+### 4.2 Indexes
+
+#### FTS5 (Text Search)
+```sql
+CREATE VIRTUAL TABLE memory_item_fts USING fts5(content);
+```
+
+#### VSS (Vector Search, 1536-dimensional example)
+```sql
+CREATE VIRTUAL TABLE memory_item_vss USING vss0(embedding(1536));
+```
+
+## 5. MCP Interface (M1 Limited)
+
+### Tools
+- `remember(content, type?, tags?, importance?, privacy_scope?)`
+- `recall(query, filters?, limit?)`
+- `forget(id, hard?)`
+- `pin(id)` / `unpin(id)`
+
+### Resources
+- `memory/{id}` (read single memory)
+
+### Prompts
+- `memory_injection(query, token_budget)`
+  - Inject top 5 related memories summarized into prompt
+
+## 6. Forgetting Policy
+
+- **Working Memory**: Deleted after 48 hours
+- **Episodic Memory**: Maintained for 90 days
+- **Semantic Memory**: Indefinite
+- **Pinned**: Excluded from deletion targets
+
+Periodically run batch jobs (cron jobs) to clean up expired records.
+
+## 7. Operation Flow
+
+### Memory Storage
+1. User calls `remember`
+2. Record in DB → Update FTS5 index → Generate embedding and record in VSS table
+
+### Memory Search
+1. User calls `recall`
+2. Keyword search with FTS5 → Vector search with VSS → Sum scores → Return top K results
+
+### Forgetting/Deletion
+1. Batch job deletes TTL expired items
+2. Immediate removal when user calls `forget`
+
+## 8. Operations and Deployment
+
+- **Runtime Environment**: Node.js (v20 or higher)
+- **Deployment Method**: Local execution
+  ```bash
+  node memory-server.js
+  ```
+- **DB Management**: Single memory.db file (stored in local storage)
+- **Backup/Restore**: Can be handled by file copying
+
+## 9. Limitations and Next Stage Considerations
+
+**Limitations**: Single user only, no permission management
+
+**Expansion Considerations**:
+- Add API Key authentication in M2
+- Switch to SQLite server mode
+- Plan to enable team collaboration using ACL (user_id, privacy_scope)
+
+## 10. Checklist
+
+- [ ] SQLite DB initial schema creation completed
+- [ ] MCP Tools (remember, recall, forget, pin/unpin) implementation completed
+- [ ] FTS5 + VSS based search working properly
+- [ ] TTL based forgetting policy batch script applied
+- [ ] MCP Client integration testing completed in local environment

package/docs/en/Memento-Milestones.md

@@ -0,0 +1,135 @@
+# 📄 MCP Memory Server Design and Milestones Document
+## 🎯 Vision
+
+Implement an AI Agent memory assistant MCP server that mimics human memory structure (working memory, episodic memory, semantic memory).
+
+- Personal (MVP): Single SQLite file based, lightweight local execution
+- Team: Internal network only server + single API Key, SQLite + serialization queue
+- Organization: Postgres + pgvector + JWT authentication, SSO/LDAP integration
+
+## 🛠 Milestone Overview
+
+| Stage | Target | Storage | Authentication | Security Scope | Operation Method |
+|-------|--------|---------|----------------|----------------|------------------|
+| M1 | Personal | SQLite Embedded | None | Local | Local execution |
+| M2 | Team | SQLite Server Mode (WAL + serialization queue) | Single API Key | Internal network only | Docker single container |
+| M3 | Organization Entry | Postgres + pgvector | JWT (user-specific tokens) | Internal network or VPN | Docker Compose (server+DB) |
+| M4 | Organization Expansion | Postgres + HA configuration | JWT + RBAC + SSO/LDAP | Enterprise security policy compliance | Kubernetes/Cloud RDS |
+
+## ⚙️ Stage-by-Stage Design
+
+### 🔹 M1. Personal Use (MVP)
+
+- **DB**: SQLite (memory.db)
+- **Indexes**: FTS5, sqlite-vec (vector search)
+- **MCP Tools**: remember, recall, forget, pin
+- **Forgetting Policy**: TTL-based (working 48h, episodic 90d, semantic indefinite)
+- **Operation**: Local execution (node memory-server.js)
+
+### 🔹 M2. Team Collaboration (Internal Network Only Server)
+
+- **DB**: SQLite (WAL mode)
+- **Write Processing**: Server-level queuing → serialization
+- **Read Processing**: Multiple concurrent reads possible
+- **Authentication**: Single API Key (API_KEY=team-secret-key)
+- **Security**: Internal network only (external ports blocked)
+- **Operation**: Docker single container
+
+```yaml
+services:
+  memory-server:
+    build: .
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./data:/app/data
+    environment:
+      - DB_PATH=/app/data/memory.db
+      - API_KEY=team-secret-key
+```
+
+- **ACL**: Apply privacy_scope (private | team)
+
+### 🔹 M3. Organization Entry (Postgres Migration)
+
+- **DB**: Postgres 15+, pgvector extension
+
+**Schema**:
+
+```sql
+CREATE TABLE memory_item (
+  id UUID PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  project_id TEXT,
+  type TEXT CHECK (type IN ('working','episodic','semantic','procedural')),
+  content TEXT,
+  importance REAL,
+  privacy_scope TEXT CHECK (privacy_scope IN ('private','team','public')) DEFAULT 'private',
+  created_at TIMESTAMPTZ DEFAULT now(),
+  last_accessed TIMESTAMPTZ,
+  embedding vector(1536),
+  content_tsv tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
+);
+CREATE INDEX ON memory_item USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+CREATE INDEX ON memory_item USING GIN (content_tsv);
+```
+
+- **Authentication**: JWT-based user-specific tokens (including user_id claim)
+- **Security**: Internal network or VPN restriction
+- **Operation**: Docker Compose (Memory Server + Postgres)
+
+### 🔹 M4. Organization Expansion (High Availability + Enterprise Security)
+
+- **DB**: Postgres cluster (HA configuration, cloud RDS possible)
+- **Authentication**: JWT + RBAC + SSO/LDAP integration
+- **Permission Model**:
+  - privacy_scope: private/team/public
+  - project_id: workspace unit
+  - RBAC (Role-Based Access Control) → admin/editor/viewer
+- **Operation**: Kubernetes, Helm Chart deployment, monitoring (Prometheus)
+- **Additional Features**: Auto archiving, backup/restore, GDPR-style deletion
+
+## 📦 MCP Interface (Common)
+
+### Tools
+
+- `remember(content, type, tags?, importance?, privacy_scope?)`
+- `recall(query, filters?, limit?)`
+- `pin(id), unpin(id)`
+- `forget(id, hard?)`
+- `summarize_thread(session_id)`
+- `link(src, dst, rel)`
+- `export(format)`
+- `feedback(memory_id, helpful?)`
+
+### Resources
+
+- `memory/{id}`
+- `memory/search?query=...`
+
+### Prompts
+
+- `memory_injection(query, token_budget)` → Inject top K related memories summarized
+
+## 🔐 Security Model Summary
+
+- **M1**: None (local only)
+- **M2**: Single API Key (team shared)
+- **M3**: JWT (user-specific tokens, can integrate with organization account server)
+- **M4**: JWT + RBAC + SSO/LDAP → Enterprise security policy compliance
+
+## 📑 Migration Guide Summary
+
+1. Extract memory_item.csv from SQLite
+2. Create schema in Postgres (pgvector, tsvector)
+3. CSV import → `\copy`
+4. Recalculate and update embeddings
+5. Replace only DB driver in MCP Memory Server
+
+## ✅ Checklist
+
+- [ ] Personal SQLite server completed
+- [ ] Team stage Docker deployment + API Key applied
+- [ ] Postgres migration documentation completed
+- [ ] Organization stage JWT authentication integration
+- [ ] Roadmap for SSO/LDAP integration confirmed