memento-mcp-server 1.6.0 → 1.7.2

package/docker-compose.yml

@@ -1,43 +0,0 @@
-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

@@ -1,217 +0,0 @@
-# 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

@@ -1,130 +0,0 @@
-# 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

@@ -1,135 +0,0 @@
-# 📄 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