memento-mcp-server 1.27.0 → 1.28.0-b

package/README.en.md

@@ -1,77 +1,56 @@
-# Memento MCP Server
+# 🧠 Memento
 
 <div align="center">
   <img src="static/logo.png" alt="Memento Logo" width="200" height="200">
-  
+
   [🇰🇷 한국어](README.md) | [🇺🇸 English](README.en.md)
 </div>
 
-AI Agent Memory Assistant MCP Server - Storage+Search+Summary+Forgetting mechanisms modeled after human memory structure
+---
 
-## 🎯 Project Overview
+LLMs forget everything when a conversation ends. Names, decisions, the debugging context you built together last week. This isn't a technical limitation — it's the absence of **memory infrastructure**.
 
-Memento MCP Server is a Model Context Protocol (MCP) server that helps AI Agents store and manage long-term memory. It simulates human memory structure (working memory, episodic memory, semantic memory, procedural memory) to provide an efficient memory management system.
+Memento is that infrastructure. Not a database that stores memories, but a **MCP-based memory operating system** where memories are created, classified, reinforced, and forgotten.
 
-## ✨ Key Features
+## Memory Is Not Simple
 
-### 🧠 Core Memory Management (MCP Client)
-- **Memory Storage**: Store 4 types of memories (working, episodic, semantic, procedural)
-- **Memory Search**: Hybrid search (text + vector)
-- **Memory Neighbors**: Vector similarity-based automatic recommendation of similar memories
-- **Memory Pinning**: Pin/unpin important memories
-- **Memory Deletion**: Soft/hard deletion
-- **Anchor System**: Set important memories as anchors for context management
-> **Note**: Anchor recovery, embedding migration, Episodic → Semantic conversion, and meta memory statistics are exposed through the HTTP Management API, not MCP tools.
+Decades of psychology and neuroscience have established one thing clearly: human memory is not a single thing.
 
-### 🔍 Advanced Search
-- **FTS5 Text Search**: SQLite's Full-Text Search
-- **Vector Search**: OpenAI embedding-based semantic search (falls back to lightweight embeddings when unavailable)
-- **Hybrid Search**: Combination of text and vector search
-- **Multi-provider Support**: TF-IDF, MiniLM, OpenAI, Gemini with automatic selection
-- **Lightweight Embedding**: TF-IDF + keyword matching fallback solution
-- **Tag-based Filtering**: Metadata-based search
+**Working memory** holds what's being processed right now. It vanishes in seconds, but in those seconds it's the foundation of every decision. **Episodic memory** is the trace of experience — "that afternoon I first learned React Hooks" — memory with time and context attached. **Semantic memory** is knowledge distilled from experience: the understanding that "TypeScript generics work like this," accumulated through hundreds of debugging sessions. And **procedural memory** is the ingrained routine — Docker deployment steps, PR checklists, team coding conventions.
 
-### 🧹 Forgetting Policy
-- **Forgetting Algorithm**: Forgetting score calculation based on recency, usage, duplication ratio
-- **Spaced Repetition**: Review scheduling based on importance and usage
-- **TTL Management**: Type-specific lifespan management
-- **Auto Cleanup**: Automated soft/hard deletion
+Most LLMs lose all four with every conversation. Memento persists all four — specify `type: working`, `episodic`, `semantic`, or `procedural` in the `remember` call and the right memory structure handles the rest.
 
-### 📊 Performance Monitoring (HTTP Management API)
-- **Security**: HTTP server splits browser-session and header-based trust. `/auth/session` starts the cookie-backed browser flow; `/admin` and `/api` require a browser session; `/api/v1/quality`, `/tools`, and `/mcp` require `Authorization: Bearer` or `X-API-Key`. See [docs/reference/en/security.md](docs/reference/en/security.md).
-- **Real-time Metrics**: Database, search, memory performance monitoring
-- **Real-time Alerts**: Automatic performance checks every 30 seconds with threshold-based alerts
-- **Error Logging**: Structured error logging and statistics collection
-- **Database Optimization**: Automatic index recommendation and creation
-- **Cache System**: LRU + TTL based caching
-- **Async Processing**: Worker pool based parallel processing
+## Living Memory
 
-### 🔗 Memory Graph View (Browser)
+This is not a simple storage layer. Memory in Memento is alive.
 
-After starting the HTTP server, you can visualize semantic relationships between memories as an interactive graph in your browser. `/dashboard` is the preferred entry point for the full admin flow, and opening `/graph` directly now offers the same `/auth/session` re-auth path so signed-out users can recover the session in place.
+Memories that matter get reinforced. Memories that grow stale get cleaned up by the forgetting algorithm. Similar memories connect to each other through vector similarity, forming a graph. Repeated procedures are version-controlled — `procedural_diff` and `procedural_rollback` let you track how a workflow evolves. Critical context gets pinned as an anchor, so the next conversation starts with that context already loaded.
 
-```
-http://localhost:9001/dashboard
-http://localhost:9001/graph
-```
+The goal is not to make AI "pretend to remember." It's to make AI an **agent that creates, classifies, reinforces, and forgets** — just like memory actually works.
 
-![Memento Memory Graph View](docs/graph-screenshot.png)
+### 📦 Monorepo Structure
 
-## 🔗 Use Memento with External AI Assistants
+This repository is an **npm workspaces** monorepo.
 
-Personal AI assistants like OpenClaw, NanoClaw, and ZeroClaw can use Memento as a shared long-term memory backend. Guide: [docs/integrations/](./docs/integrations/README.md)
+| Path | Description |
+|------|-------------|
+| **packages/memento-core** (`@memento/core`) | Domain, infrastructure, and shared library. Entry points: `createMementoCore`, `createToolContext`, `getToolRegistry`, `closeDatabase`. DB init and migration run from the root via `npm run db:init` / `npm run db:migrate`. |
+| **packages/memento-server** | MCP/HTTP server built on core. Run via root `npm run dev`, `npm start`, `npm run dev:http`, etc. |
+| **packages/memento-client** (`@memento/client`) | Client library for connecting to the server. |
+| **apps/** | Experimental apps (e.g., `experimental-example` uses `@memento/core` in-process). |
 
-Use the `@memento/assistant` SDK for deterministic auto recall/remember with just two hooks — [SDK quickstart](./docs/integrations/_shared/sdk-quickstart.md)
+For detailed structure, build, and test commands, see [AGENTS.md](AGENTS.md).
 
 ## 🚀 Quick Start
 
-### 🥇 **One-click Installation (Recommended)**
+> **📦 Package manager**: This project uses **npm**. `pnpm` and `yarn` are not supported.
+
+### One-click Installation (Recommended)
 ```bash
-# Run automatic installation script
 curl -sSL https://raw.githubusercontent.com/jee1/memento/main/install.sh | bash
 ```
 
-### 🥈 **npx Method (For Developers)**
+### npx Method (For Developers)
 ```bash
 # Run immediately (without installation)
 npx memento-mcp-server@latest dev
@@ -81,31 +60,101 @@ npx memento-mcp-server@latest setup
 npx memento-mcp-server@latest start
 ```
 
-### 🥉 **Docker Method (For Production)**
-```bash
-# Development environment
-docker-compose -f docker-compose.dev.yml up -d
+**Repeated use**: Running via npx each time triggers a download. For frequent use, prefer **global install** (`npm i -g memento-mcp-server`) or local install with `./node_modules/.bin/memento`. Mode breakdown: MCP server (`memento-mcp-server` / stdio), HTTP server (`memento-dev`), CLI (`memento` — recall, remember, forget, memory_injection). CLI guide: [docs/guides/ko/memento-cli-for-ai.md](docs/guides/ko/memento-cli-for-ai.md).
 
-# Production environment
-docker-compose -f docker-compose.prod.yml up -d
+### Docker Method (For Production)
+```bash
+docker-compose -f docker-compose.dev.yml up -d   # Development
+docker-compose -f docker-compose.prod.yml up -d  # Production
 ```
 
-### 🛠️ **Source Code Method (For Developers)**
+### Source Code Method (For Developers)
 ```bash
-# Clone repository
 git clone https://github.com/jee1/memento.git
 cd memento
-
-# One-click installation and run
 npm run quick-start
 ```
 
-### 📚 **Detailed Installation Guide**
 For detailed installation methods, see [INSTALL.en.md](INSTALL.en.md).
 
+### HTTP MCP Server for Multi-Agent Deployments
+
+SQLite only allows one writer at a time, even in WAL mode. Multiple AI agents calling `remember`/`forget` in separate processes will hit `SQLITE_BUSY`. The solution: **run a single MCP server process** that owns the database exclusively.
+
+```bash
+npm run dev:http                          # Development (hot reload)
+npm run build && npm run start:http       # Production
+```
+
+With this setup, all agents connect to one HTTP/WebSocket interface, and the SQLite writer stays in a single process.
+
+## 🔗 Use with External AI Assistants
+
+Personal AI assistants like OpenClaw, NanoClaw, and ZeroClaw can use Memento as a shared long-term memory backend. Guide: [docs/integrations/](./docs/integrations/README.md)
+
+Use the `@memento/assistant` SDK for automatic recall/remember in two lines of code — [SDK quickstart](./docs/integrations/_shared/sdk-quickstart.md)
+
 ## 🛠️ Usage
 
-### MCP Client Connection
+Three ways to connect to Memento:
+
+- **mcp.json config**: Register Memento in MCP host apps like Claude Desktop, Cursor, or Claude Code — no code required
+- **MCP protocol** (`@modelcontextprotocol/sdk`): Connect directly from custom agent code
+- **HTTP API client** (`@memento/client`): Call Memento's REST API from TypeScript/JavaScript applications
+
+### mcp.json Config (Claude Desktop · Cursor · Claude Code)
+
+#### stdio mode (single agent)
+
+After `npm run build`:
+
+```json
+{
+  "mcpServers": {
+    "memento": {
+      "command": "node",
+      "args": ["/path/to/memento/packages/memento-server/dist/server/index.js"],
+      "env": {
+        "DB_PATH": "/absolute/path/to/data/memory.db"
+      }
+    }
+  }
+}
+```
+
+#### HTTP MCP mode (shared multi-agent server)
+
+```bash
+npm run build && npm run start:http   # default port: 8080
+```
+
+```json
+{
+  "mcpServers": {
+    "memento": {
+      "type": "http",
+      "url": "http://127.0.0.1:8080/mcp"
+    }
+  }
+}
+```
+
+> **Using npx** (without building from source):
+> ```json
+> {
+>   "mcpServers": {
+>     "memento": {
+>       "command": "npx",
+>       "args": ["memento-mcp-server@latest"],
+>       "env": {
+>         "DB_PATH": "/absolute/path/to/data/memory.db"
+>       }
+>     }
+>   }
+> }
+> ```
+
+### MCP Protocol (`@modelcontextprotocol/sdk`)
 
 ```typescript
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -114,61 +163,136 @@ const client = new Client({
   name: "memento-client",
   version: "0.1.0"
 }, {
-  capabilities: {
-    tools: {},
-    resources: {},
-    prompts: {}
-  }
+  capabilities: { tools: {}, resources: {}, prompts: {} }
 });
 
 // stdio connection
 await client.connect({
   command: "node",
-  args: ["dist/server/index.js"]
+  args: ["packages/memento-server/dist/server/index.js"]
 });
 
-// WebSocket connection
+// HTTP MCP connection (shared multi-agent server)
 await client.connect({
   transport: {
-    type: "websocket",
-    url: "ws://localhost:8080/mcp"
+    type: "http",
+    url: "http://127.0.0.1:7777"
   }
 });
 ```
 
-### Memory Storage
-
 ```typescript
 // Store memory
-const result = await client.callTool({
+await client.callTool({
   name: "remember",
   arguments: {
-    content: "I learned about React Hooks. useState manages state and useEffect handles side effects.",
+    content: "I learned about React Hooks. useState manages state, useEffect handles side effects.",
     type: "episodic",
     tags: ["react", "hooks", "javascript"],
     importance: 0.8
   }
 });
-```
-
-### Memory Search
 
-```typescript
 // Search memory
 const results = await client.callTool({
   name: "recall",
   arguments: {
-    query: "React Hook",
-    filters: {
-      type: ["episodic", "semantic"],
-      tags: ["react"]
-    },
+    query: "What do I need to know about React Hooks?",
+    filters: { type: ["episodic", "semantic"], tags: ["react"] },
     limit: 10
   }
 });
 ```
 
-## 📋 API Documentation
+### HTTP API Client (`@memento/client`)
+
+`@memento/client` is an **HTTP REST API wrapper**, not an MCP client. Use it to call Memento's `/tools/*` endpoints directly from TypeScript/JavaScript applications.
+
+```typescript
+import { MementoClient } from "@memento/client";
+
+const client = new MementoClient({
+  serverUrl: "http://localhost:8080",
+  apiKey: "your-api-key"
+});
+
+await client.connect();  // health check
+
+const result = await client.remember({
+  content: "I learned about React Hooks.",
+  type: "episodic",
+  tags: ["react", "hooks"],
+  importance: 0.8
+});
+
+const results = await client.recall(
+  "What should I know when first learning React Hooks?",
+  { type: ["episodic", "semantic"], tags: ["react"] },
+  10
+);
+
+await client.pin(result.memory_id);
+await client.forget(result.memory_id);
+```
+
+## 🧠 Features
+
+### Core Memory Management (MCP Client)
+
+14 tools are exposed via MCP. Operational functions (anchor restore, embedding migration, episodic→semantic conversion, meta stats) are HTTP API only.
+
+- **Memory storage**: `working`, `episodic`, `semantic`, `procedural` types
+- **Memory search**: Hybrid search (FTS5 text + vector)
+- **Memory neighbors**: Vector similarity-based automatic recommendation
+- **Memory pinning**: Pin/unpin important memories
+- **Memory deletion**: Soft/hard deletion
+- **Anchor system**: Pin critical memories as anchors for instant context restoration in new conversations
+
+> **Note**: Anchor recovery, embedding migration, Episodic → Semantic conversion, and meta memory statistics are exposed through the HTTP Management API, not MCP tools.
+
+### 🔍 Hybrid Search
+
+Text and semantic (vector) search combined. Even when you don't remember the exact keyword, similar concepts surface.
+
+- **FTS5 text search**: SQLite Full-Text Search
+- **Vector search**: sqlite-vec semantic similarity search
+- **Hybrid search**: Combined scoring (Consolidation Score weighting)
+- **Multi-provider support**: TF-IDF, MiniLM, OpenAI, Gemini with automatic selection
+- **Auto fallback**: If a provider fails, automatically switches to the next
+- **Tag-based filtering**: Metadata-based search
+
+### 🧹 Forgetting Policy
+
+A memory system is only useful if it also forgets. Memories that only accumulate become noise.
+
+- **Forgetting algorithm**: Score based on recency, usage frequency, and duplication ratio
+- **Spaced repetition**: Review scheduling based on importance and usage
+- **TTL management**: Type-specific lifespans (working 2d, episodic 30d, semantic 180d, procedural 90d)
+- **Auto cleanup**: Automated soft/hard deletion
+
+### 📊 Performance Monitoring (HTTP Management API)
+
+- **Security**: HTTP server splits browser-session and header-based trust. `/auth/session` starts the cookie-backed browser flow; `/admin` and `/api` require a browser session; `/api/v1/quality`, `/tools`, and `/mcp` require `Authorization: Bearer` or `X-API-Key`. See [docs/reference/en/security.md](docs/reference/en/security.md).
+
+- **Real-time metrics**: Database, search, memory performance monitoring
+- **Real-time alerts**: Automatic performance checks every 30 seconds with threshold-based alerts
+- **Error logging**: Structured error logging and statistics collection
+- **Database optimization**: Automatic index recommendation and creation
+- **Cache system**: LRU + TTL based caching
+- **Async processing**: Worker pool based parallel processing
+
+### 🔗 Memory Graph View (Browser)
+
+After starting the HTTP server, visualize semantic relationships between memories as an interactive graph. `/dashboard` is the preferred entry point for the full admin flow; opening `/graph` directly now offers the same `/auth/session` re-auth path for session recovery.
+
+```
+http://localhost:9001/dashboard
+http://localhost:9001/graph
+```
+
+![Memento Memory Graph View](docs/graph-screenshot.png)
+
+## 📋 API Reference
 
 ### MCP Tools (Core 14)
 
@@ -200,15 +324,17 @@ const results = await client.callTool({
 | `procedural_diff` | Compare procedural memory versions | left_id, right_id |
 | `procedural_rollback` | Roll back procedural memory to a previous version | current_id, target_version_id |
 
-**HTTP-only (not MCP)**: `restore_anchors`, `migrate_embeddings`, `convert_episodic_to_semantic`, `get_meta_memory_stats` - see the HTTP Management API below.
+**HTTP-only (not MCP)**: `restore_anchors`, `migrate_embeddings`, `convert_episodic_to_semantic`, `get_meta_memory_stats` — see HTTP Management API below.
 
 ### HTTP Management API
 
+> **Important**: The following functions are not exposed via MCP and are only available through the HTTP API.
+
 | Endpoint | Description | Method |
 |----------|-------------|--------|
 | `/admin/memory/cleanup` | Memory cleanup | POST |
 | `/admin/memory/review-candidates` | Memory review candidate queue | GET |
-| `/admin/memory/items/:memory_id` | Single memory JSON preview (dashboard, etc.) | GET |
+| `/admin/memory/items/:memory_id` | Single memory JSON preview | GET |
 | `/admin/memory/review-candidates/:id/review` | Mark review candidate as reviewed | POST |
 | `/admin/memory/review-candidates/:id/dismiss` | Dismiss review candidate | POST |
 | `/admin/stats/forgetting` | Forgetting statistics | GET |
@@ -217,8 +343,10 @@ const results = await client.callTool({
 | `/admin/errors/resolve` | Resolve errors | POST |
 | `/admin/alerts/performance` | Performance alerts | GET |
 | `/admin/database/optimize` | Database optimization | POST |
+| `/admin/anchors/restore` | Restore anchors | POST |
+| `/admin/embeddings/migrate` | Embedding migration | POST |
 
-**Other HTTP admin**: Batch status/run (`/admin/batch/*`, including `jobType` `memory_review_candidates`), performance metrics/alerts (`/admin/performance/*`), relation extract/get/visualize (`/admin/relations/*`). See [docs/api/en/api-reference.md](docs/api/en/api-reference.md). For the memory review MVP (endpoints, env, batch), use the **"Memory review candidates (MVP)"** section there.
+**Other HTTP admin**: Batch status/run (`/admin/batch/*`, including `memory_review_candidates`), performance metrics/alerts (`/admin/performance/*`), relation extract/get/visualize (`/admin/relations/*`). See [docs/api/en/api-reference.md](docs/api/en/api-reference.md).
 
 ### Resources
 
@@ -241,10 +369,10 @@ const results = await client.callTool({
 | `GEMINI_API_KEY` | - | Gemini API key (optional) |
 | `EMBEDDING_PROVIDER` | minilm | Embedding provider (tfidf, lightweight, minilm, openai, gemini) |
 | `CORS_ALLOWED_ORIGINS` | (empty) | CORS allowed origins (comma-separated; empty = no cross-origin) |
-| `ENABLE_PII_MASKING` | true | PII masking (security; see [docs/reference/en/security.md](docs/reference/en/security.md)) |
-| `MEMORY_REVIEW_IMPORTANCE_THRESHOLD` | `0.7` | Memory review: minimum importance (0-1). Details in [docs/api/en/api-reference.md](docs/api/en/api-reference.md) ("Memory review candidates (MVP)") |
+| `ENABLE_PII_MASKING` | true | PII masking (see [docs/reference/en/security.md](docs/reference/en/security.md)) |
+| `MEMORY_REVIEW_IMPORTANCE_THRESHOLD` | `0.7` | Memory review: minimum importance (0-1) |
 | `MEMORY_REVIEW_STALE_DAYS` | `14` | Memory review: minimum stale age in days (integer ≥ 1) |
-| `MEMORY_REVIEW_MAX_CANDIDATES` | `50` | Memory review: max candidates from selection (integer ≥ 1) |
+| `MEMORY_REVIEW_MAX_CANDIDATES` | `50` | Memory review: max candidates (integer ≥ 1) |
 | `MEMORY_REVIEW_CANDIDATES_INTERVAL_MS` | `86400000` | `memory_review_candidates` batch interval in ms (minimum `60000`) |
 | `MEMORY_REVIEW_CANDIDATE_DUE_DAYS` | `14` | Days added when the batch computes `due_at` (1–366) |
 
@@ -253,12 +381,10 @@ const results = await client.callTool({
 ### Forgetting Policy Configuration
 
 ```bash
-# Forgetting thresholds
 FORGET_THRESHOLD=0.6
 SOFT_DELETE_THRESHOLD=0.6
 HARD_DELETE_THRESHOLD=0.8
 
-# TTL settings (in days)
 TTL_SOFT_WORKING=2
 TTL_SOFT_EPISODIC=30
 TTL_SOFT_SEMANTIC=180
@@ -268,108 +394,64 @@ TTL_SOFT_PROCEDURAL=90
 ## 🧪 Testing
 
 ```bash
-# Run all tests (Vitest)
 npm run test
 
-# Run individual tests
-npm run test:client                    # Client tests
-npm run test:search                    # Search functionality tests
-npm run test:embedding                 # Embedding functionality tests
-npm run test:lightweight-embedding     # Lightweight embedding tests
-npm run test:gemini-embedding         # Gemini embedding tests
-npm run test:forgetting                # Forgetting policy tests
-npm run test:performance               # Performance benchmarks
-npm run test:monitoring                # Performance monitoring tests
-npm run test:error-logging             # Error logging tests
-npm run test:performance-alerts        # Performance alert tests
-npm run test:vector-search             # Vector search tests
-npm run test:memory-injection         # Memory injection tests
-npm run test:batch-scheduler           # Batch scheduler tests
-npm run test:embedding-benchmark       # Embedding performance benchmark
-npm run test:all-embedding             # All embedding-related Vitest files
-
-# Test watch mode
-npm run test -- --watch
+npm run test:client
+npm run test:search
+npm run test:embedding
+npm run test:lightweight-embedding
+npm run test:gemini-embedding
+npm run test:forgetting
+npm run test:performance
+npm run test:monitoring
+npm run test:error-logging
+npm run test:performance-alerts
+npm run test:vector-search
+npm run test:memory-injection
+npm run test:batch-scheduler
+npm run test:embedding-benchmark
 
-# Tests with coverage
+npm run test -- --watch
 npm run test -- --coverage
 ```
 
 ## 📚 Developer Guidelines
 
-### Repository Guidelines (`AGENTS.md`)
-- **Project Structure**: npm workspaces — code lives under `packages/memento-core`, `packages/memento-server`, `packages/memento-client`, plus `apps/` and root-level `tests/`. See [AGENTS.md](AGENTS.md).
-- **Build/Test Commands**: `npm run dev`, `npm run build`, `npm run test`, etc.
-- **Coding Style**: Node.js ≥ 24, TypeScript ES modules, 2-space indentation
-- **Testing Guidelines**: Vitest; colocate `*.spec.ts` under each package `src/`, workspace-level specs under root `tests/`, and scenario drivers under `packages/*/src/test/` where applicable.
-- **Commit/PR Guidelines**: Conventional Commits, Korean context included
-- **Environment/Database**: `.env` configuration, `data/` folder management
-
-## 📊 Performance Metrics
-
-### Basic Performance
-- **Database Performance**: Average query time 0.16-0.22ms
-- **Search Performance**: 0.78-4.24ms (improved with cache effects)
-- **Memory Usage**: 11-15MB heap usage
-- **Concurrent Connections**: Supports up to 1000 connections
-
-### Advanced Performance Optimization
-- **Cache Hit Rate**: 80%+ (search result caching)
-- **Embedding Caching**: 24-hour TTL for cost savings
-- **Async Processing**: Worker pool based parallel processing
-- **Database Optimization**: Automatic index recommendation and creation
-- **Real-time Monitoring**: Automatic performance checks every 30 seconds
-- **Error Logging**: Structured error tracking and statistics
-- **Performance Alerts**: Threshold-based automatic alert system
-
-### Embedding Provider Performance
+- **Project structure**: npm workspaces — `packages/memento-core`, `packages/memento-server`, `packages/memento-client`, `apps/*`. See [AGENTS.md](AGENTS.md).
+- **Build/test**: `npm run dev`, `npm run build`, `npm run test`, etc.
+- **Coding style**: Node.js ≥ 24, TypeScript ES modules, 2-space indentation
+- **Testing**: Vitest; colocate `*.spec.ts` under each package `src/`, workspace-level specs under root `tests/`
+- **Commit/PR**: Conventional Commits, Korean context included
+
+## 📊 Performance
+
+### Benchmarks
+- **Database**: average query time 0.16–0.22ms
+- **Search**: 0.78–4.24ms (improved with cache effects)
+- **Memory usage**: 11–15MB heap
+- **Concurrent connections**: up to 1000
+
+### Embedding Provider Comparison
 
 #### Free Providers (Local Processing)
-- **TF-IDF**: 512 dimensions, extremely fast (0.82ms), low memory usage (4.48MB)
-- **MiniLM**: 384 dimensions, balanced performance, multilingual support
+- **TF-IDF**: 512 dimensions, extremely fast (0.82ms), low memory (4.48MB)
+- **MiniLM**: 384 dimensions, balanced performance, multilingual
 
 #### Paid Providers (Cloud API)
-- **OpenAI**: 1536 dimensions, highest performance, high accuracy
-- **Gemini**: 768 dimensions, high performance, multilingual support
-
-**Auto Selection and Priority Order**:
-1. **Explicit Request**: If a specific provider is requested in API call, it takes priority
-2. **Configuration Default**: Uses `EMBEDDING_PROVIDER` value from `.env` file
-3. **Automatic Priority Selection**: Automatically selects available providers in the following order:
-   - 1st Priority: **OpenAI** (paid, highest performance)
-   - 2nd Priority: **Gemini** (paid, high performance)
-   - 3rd Priority: **MiniLM** (free, balanced performance)
-   - 4th Priority: **TF-IDF** (free, fast speed)
-
-**Fallback Mechanism**: Automatically falls back to the next priority provider if a higher priority provider fails.
-
-## 🏗️ Architecture
-
-### M1: Personal Use (Current Implementation)
-- **Storage**: better-sqlite3 embedded
-- **Index**: FTS5 + sqlite-vec
-- **Authentication**: Split browser-session and header-based trust model (`/auth/session` starts the cookie-backed browser flow; `/admin` and `/api` require a browser session; `/api/v1/quality`, `/tools`, and `/mcp` require `Authorization: Bearer` or `X-API-Key`)
-- **Operation**: Local execution
-- **MCP Client**: Exposes 14 core tools
-- **Management Functions**: Separated into HTTP API
-- **Additional Features**: 
-  - Multiple embedding providers (TF-IDF, MiniLM, OpenAI, Gemini)
-  - Performance monitoring and alert system
-  - Cache system
-  - Anchor system (context management)
-  - Relation graph (semantic relation extraction)
-  - Meta memory statistics
-  - Consolidation score system
-
-### M2: Team Collaboration (Planned)
-- **Storage**: SQLite server mode
-- **Authentication**: API Key
-- **Operation**: Docker single container
-
-### M3: Organization Entry (Planned)
-- **Storage**: PostgreSQL + pgvector
-- **Authentication**: JWT
-- **Operation**: Docker Compose
+- **OpenAI**: 1536 dimensions, highest accuracy
+- **Gemini**: 768 dimensions, high performance, multilingual
+
+**Auto selection order**: explicit request → `.env` `EMBEDDING_PROVIDER` → OpenAI(1) → Gemini(2) → MiniLM(3) → TF-IDF(4). Automatic fallback on provider failure.
+
+## 🏗️ Architecture Journey
+
+Memento is designed to grow: from a personal local server, through team collaboration, to an organization-scale memory platform.
+
+**M1: Personal (current)** — the form you can use today. SQLite embedded, FTS5 + sqlite-vec indexes, local execution. **Authentication**: Split browser-session and header-based trust model (`/auth/session` cookie flow, `/admin`·`/api` require browser session, `/tools`·`/mcp` require Bearer/API-Key). 14 MCP tools, management functions separated into HTTP API.
+
+**M2: Team (planned)** — SQLite server mode, API Key auth, Docker single container. Multiple teammates share one memory backend.
+
+**M3: Organization (planned)** — PostgreSQL + pgvector, JWT auth, Docker Compose. Hundreds of agents share organizational memory.
 
 ## 🤝 Contributing
 
@@ -379,25 +461,18 @@ npm run test -- --coverage
 4. Push to the Branch (`git push origin feature/AmazingFeature`)
 5. Open a Pull Request
 
-### Development Environment Setup
+### Development Setup
 ```bash
-# Fork and clone repository
 git clone https://github.com/your-username/memento.git
 cd memento
-
-# Install dependencies
 npm install
-
-# Start development server
 npm run dev
-
-# Run tests
 npm run test
 ```
 
 ## 📄 License
 
-This project is distributed under the MIT License. See the `LICENSE` file for details.
+MIT License. See the `LICENSE` file for details.
 
 ## 📞 Support
 
@@ -408,9 +483,9 @@ This project is distributed under the MIT License. See the `LICENSE` file for de
 
 ## 🙏 Acknowledgments
 
-- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP Protocol
-- [OpenAI](https://openai.com/) - Embedding Service
-- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - High-performance SQLite driver
-- [Express](https://expressjs.com/) - Web framework
-- [Vitest](https://vitest.dev/) - Testing framework
-- [TypeScript](https://www.typescriptlang.org/) - Development language
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [OpenAI](https://openai.com/)
+- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
+- [Express](https://expressjs.com/)
+- [Vitest](https://vitest.dev/)
+- [TypeScript](https://www.typescriptlang.org/)