memento-mcp-server 1.29.0 → 1.30.0-b

package/INSTALL.en.md

@@ -10,6 +10,15 @@ How you install Memento depends on **how fast you want to try it** and **how muc
 
 ## 📋 Installation Method Selection
 
+### 🧩 **Claude Code users: install the plugin**
+```
+/plugin marketplace add jee1/memento
+/plugin install memento@memento
+```
+This registers the MCP server and ships a skill for the `recall` → `remember` loop. The memory database lives at `${CLAUDE_PLUGIN_DATA}/memory.db` and survives plugin updates.
+
+Four MCP tools are advertised by default: `recall`, `remember`, `memory_injection`, and `feedback`. To reach the rest — anchors, procedural versioning, introspection — add `MEMENTO_TOOLSET=full` to the `memento` server's `env` block in your user or project MCP config (edits to the plugin's own `.mcp.json` are lost on update).
+
 ### 🥇 **1st Priority: One-click Installation (Recommended)**
 ```bash
 # Run automatic installation script
@@ -87,9 +96,9 @@ npx memento-mcp-server@latest setup
 npm install -g memento-mcp-server
 
 # Usage
-memento-mcp dev
-memento-mcp start
-memento-mcp setup
+memento-mcp-server dev
+memento-mcp-server start
+memento-mcp-server setup
 ```
 
 ### 3. Docker Method

package/INSTALL.md

@@ -10,6 +10,15 @@ Memento를 설치하는 방법은 **얼마나 빨리 써 보고 싶은지**, **
 
 ## 📋 설치 방법 선택
 
+### 🧩 **Claude Code 사용자: 플러그인 설치**
+```
+/plugin marketplace add jee1/memento
+/plugin install memento@memento
+```
+MCP 서버 등록과 `recall`→`remember` 습관 skill이 함께 설치되고, 기억 DB는 `${CLAUDE_PLUGIN_DATA}/memory.db`에 보관되어 업데이트 후에도 유지됩니다.
+
+기본으로 노출되는 MCP 도구는 `recall`·`remember`·`memory_injection`·`feedback` 4개입니다. 앵커·절차 버전관리·introspection 같은 나머지 도구까지 쓰려면 사용자/프로젝트 MCP 설정의 `memento` 서버 `env`에 `MEMENTO_TOOLSET=full`을 추가하세요 (플러그인 내부 `.mcp.json` 수정은 업데이트 시 사라집니다).
+
 ### 🥇 **1순위: 원클릭 설치 (권장)**
 ```bash
 # 자동 설치 스크립트 실행
@@ -100,9 +109,9 @@ npx memento-mcp-server@latest dev
 npm install -g memento-mcp-server
 
 # 사용법
-memento-mcp dev
-memento-mcp start
-memento-mcp setup
+memento-mcp-server dev
+memento-mcp-server start
+memento-mcp-server setup
 ```
 
 ### 3. Docker 방식

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Memento Team
+
+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 OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -4,6 +4,8 @@
   <img src="static/logo.png" alt="Memento Logo" width="200" height="200">
 
   [🇰🇷 한국어](README.md) | [🇺🇸 English](README.en.md)
+
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 </div>
 
 ---
@@ -30,15 +32,22 @@ The goal is not to make AI "pretend to remember." It's to make AI an **agent tha
 
 ### 📦 Monorepo Structure
 
-This repository is an **npm workspaces** monorepo. `@memento/core` holds domain logic, the database, and MCP tools; `memento-server` exposes them over stdio and HTTP. Use `@memento/client` for REST from your apps, `@memento/assistant` to wire external assistants, and `@memento/agent-integration` for session and provenance contracts. Experiments live under `apps/`.
+This repository is an **npm workspaces** monorepo. `@memento/core` holds domain logic, the database, and MCP tools; `memento-server` exposes them over stdio and HTTP. Use `@jee1/memento-client` for REST from your apps, `@jee1/memento-assistant` to wire external assistants, and `@memento/agent-integration` for session and provenance contracts — the latter is **internal only** and is not published to npm (it ships bundled inside the server tarball). Experiments live under `apps/`.
+
+Three packages are published to npm: `memento-mcp-server` (the server), `@jee1/memento-client`, and `@jee1/memento-assistant`.
+
+```bash
+npm i @jee1/memento-client      # REST client
+npm i @jee1/memento-assistant   # auto recall/save SDK for external assistants
+```
 
 | 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. |
-| **packages/memento-assistant** (`@memento/assistant`) | SDK for external AI assistants (recall/remember). |
-| **packages/memento-agent-integration** (`@memento/agent-integration`) | Agent integration contracts and adapters. |
+| **packages/memento-client** (`@jee1/memento-client`) | Client library for connecting to the server. |
+| **packages/memento-assistant** (`@jee1/memento-assistant`) | SDK for external AI assistants (recall/remember). |
+| **packages/memento-agent-integration** (`@memento/agent-integration`) | Agent integration contracts and adapters. Internal only (`private`), not published to npm. |
 | **apps/** | Experimental apps (e.g., `experimental-example` uses `@memento/core` in-process). |
 
 For detailed structure, build, and test commands, see [AGENTS.md](AGENTS.md).
@@ -64,6 +73,27 @@ npx memento-mcp-server@latest start
 
 **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).
 
+### Claude Code Plugin (recommended — zero config)
+
+This repository is itself a plugin marketplace. Installing the plugin registers the MCP server and ships a skill that teaches the `recall` → `remember` loop.
+
+```
+/plugin marketplace add jee1/memento
+/plugin install memento@memento
+```
+
+The memory database lives at `${CLAUDE_PLUGIN_DATA}/memory.db`, so it survives plugin updates. After installing, check the `/plugin` panel to confirm the `memento` MCP server is connected.
+
+### Official MCP Registry
+
+Memento is listed in the official MCP registry as `io.github.jee1/memento-mcp-server`. Registry-aware clients and marketplaces resolve it by that name.
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jee1/memento-mcp-server"
+```
+
+The listing metadata lives in the root [`server.json`](server.json); every stable release publishes it automatically from `release.yml` after the npm publish (pre-releases are not listed).
+
 ### Docker Method (For Production)
 ```bash
 docker-compose -f docker-compose.dev.yml up -d   # Development
@@ -94,7 +124,7 @@ With this setup, all agents connect to one HTTP/WebSocket interface, and the SQL
 
 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)
+Use the `@jee1/memento-assistant` SDK for automatic recall/remember in two lines of code — [SDK quickstart](./docs/integrations/_shared/sdk-quickstart.md)
 
 ## 🛠️ Usage
 
@@ -102,7 +132,7 @@ 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
+- **HTTP API client** (`@jee1/memento-client`): Call Memento's REST API from TypeScript/JavaScript applications
 
 ### mcp.json Config (Claude Desktop · Cursor · Claude Code)
 
@@ -206,12 +236,12 @@ const results = await client.callTool({
 });
 ```
 
-### HTTP API Client (`@memento/client`)
+### HTTP API Client (`@jee1/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.
+`@jee1/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";
+import { MementoClient } from "@jee1/memento-client";
 
 const client = new MementoClient({
   serverUrl: "http://localhost:9001",
@@ -241,7 +271,7 @@ await client.forget(result.memory_id);
 
 ### Core Memory Management (MCP Client)
 
-22 tools are exposed via MCP. Operational functions (anchor restore, embedding migration, episodic→semantic conversion, meta stats) are HTTP API only.
+22 tools are registered, but `tools/list` advertises only four by default (v1.18+): `recall`, `remember`, `memory_injection`, `feedback`. Tool definitions occupy the client's context for the whole session, and Memento is a server people leave running — trimming the default listing cuts that from ~5,860 to ~2,954 estimated tokens (49.6%). The other 18 stay registered and callable; they are only withheld from the listing. Set `MEMENTO_TOOLSET=full` to advertise all of them. Operational functions (anchor restore, embedding migration, episodic→semantic conversion, meta stats) remain HTTP API only.
 
 - **Memory storage**: `working`, `episodic`, `semantic`, `procedural` types
 - **Memory search**: Hybrid search (FTS5 text + vector)
@@ -433,6 +463,8 @@ npm run test -- --watch
 npm run test -- --coverage
 ```
 
+Retrieval quality against public datasets (LongMemEval-S, LoCoMo) runs through the same harness: acquire with `npm run quality:longmemeval:acquire` / `npm run quality:locomo:acquire`, then run `npm run quality:locomo:benchmark`. Raw datasets are never committed, and LoCoMo is **CC BY-NC 4.0 (NonCommercial)**, so its numbers cannot back commercial claims. The procedure and current results live in [benchmark-datasets.md](docs/_work/testing/ko/benchmark-datasets.md); the production search path does not yet beat a plain FTS baseline, so these figures are kept as an internal regression metric rather than published.
+
 ## 📚 Developer Guidelines
 
 - **Project structure**: npm workspaces — `packages/memento-core`, `packages/memento-server`, `packages/memento-client`, `apps/*`. See [AGENTS.md](AGENTS.md).
@@ -465,7 +497,7 @@ npm run test -- --coverage
 
 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). 22 MCP tools, management functions separated into HTTP API.
+**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). 22 registered MCP tools with four listed by default (`MEMENTO_TOOLSET=full` lists all), management functions separated into HTTP API.
 
 **M2: Team (planned)** — SQLite server mode, API Key auth, Docker single container. Multiple teammates share one memory backend.
 
@@ -490,7 +522,7 @@ npm run test
 
 ## 📄 License
 
-MIT License. See the `LICENSE` file for details.
+This project is released under the [MIT License](LICENSE). Matches `package.json` `"license": "MIT"`.
 
 ## 📞 Support
 

package/README.md

@@ -4,6 +4,8 @@
   <img src="static/logo.png" alt="Memento Logo" width="200" height="200">
 
   [🇰🇷 한국어](README.md) | [🇺🇸 English](README.en.md)
+
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 </div>
 
 ---
@@ -30,15 +32,22 @@ AI가 "기억하는 척"하는 것이 아니라, 기억을 생성·분류·강
 
 ### 📦 모노레포 구조
 
-이 저장소는 **npm workspaces** 모노레포입니다. `@memento/core`가 도메인·DB·MCP 도구를 담고, `memento-server`가 stdio/HTTP로 이를 노출합니다. 앱이나 스크립트에서 REST로 붙을 때는 `@memento/client`, OpenClaw 같은 외부 비서에는 `@memento/assistant`, 에이전트 세션·프로버넌스 계약에는 `@memento/agent-integration`을 씁니다. 실험 코드는 `apps/` 아래에 두었습니다.
+이 저장소는 **npm workspaces** 모노레포입니다. `@memento/core`가 도메인·DB·MCP 도구를 담고, `memento-server`가 stdio/HTTP로 이를 노출합니다. 앱이나 스크립트에서 REST로 붙을 때는 `@jee1/memento-client`, OpenClaw 같은 외부 비서에는 `@jee1/memento-assistant`, 에이전트 세션·프로버넌스 계약은 `@memento/agent-integration`이 담당하지만 이는 **내부 전용 패키지**로 npm에 발행되지 않습니다(서버 tarball에 번들). 실험 코드는 `apps/` 아래에 두었습니다.
+
+npm에 발행되는 패키지는 셋입니다: `memento-mcp-server`(서버), `@jee1/memento-client`, `@jee1/memento-assistant`.
+
+```bash
+npm i @jee1/memento-client      # REST 클라이언트
+npm i @jee1/memento-assistant   # 외부 비서용 auto-recall/save SDK
+```
 
 | 경로 | 설명 |
 |------|------|
 | **packages/memento-core** (`@memento/core`) | 도메인·인프라·공유 라이브러리. 진입점: `createMementoCore`, `createToolContext`, `getToolRegistry`, `closeDatabase`. DB 초기화·마이그레이션은 루트에서 `npm run db:init` / `npm run db:migrate`로 실행. |
 | **packages/memento-server** | core를 사용하는 MCP/HTTP 서버. 루트 `npm run dev`, `npm start`, `npm run dev:http` 등으로 실행. |
-| **packages/memento-client** (`@memento/client`) | 서버 연결용 클라이언트 라이브러리. |
-| **packages/memento-assistant** (`@memento/assistant`) | 외부 AI 비서용 recall/remember SDK. |
-| **packages/memento-agent-integration** (`@memento/agent-integration`) | 에이전트 통합 계약·어댑터. |
+| **packages/memento-client** (`@jee1/memento-client`) | 서버 연결용 클라이언트 라이브러리. |
+| **packages/memento-assistant** (`@jee1/memento-assistant`) | 외부 AI 비서용 recall/remember SDK. |
+| **packages/memento-agent-integration** (`@memento/agent-integration`) | 에이전트 통합 계약·어댑터. 내부 전용(`private`), npm 미발행. |
 | **apps/** | 실험용 앱 (예: `experimental-example`은 `@memento/core`를 in-process로 사용). |
 
 상세 구조·빌드·테스트 명령은 [AGENTS.md](AGENTS.md)를 참조하세요.
@@ -75,6 +84,27 @@ npx memento-mcp-server@latest setup
 
 **반복 사용 시 주의**: 매번 npx로 실행하면 다운로드가 발생할 수 있으므로 반복 사용에는 **글로벌 설치**(`npm i -g memento-mcp-server`) 또는 로컬 설치 후 `./node_modules/.bin/memento` 사용을 권장합니다. 모드 구분: MCP 서버(`memento-mcp-server` / stdio), HTTP 서버(`memento-dev`), CLI(`memento` — recall, remember, forget, memory_injection). CLI 가이드: [docs/guides/ko/memento-cli-for-ai.md](docs/guides/ko/memento-cli-for-ai.md).
 
+### Claude Code 플러그인 (권장 — 설정 없이 한 번에)
+
+이 저장소 자체가 플러그인 마켓플레이스입니다. MCP 서버 등록과 `recall`→`remember` 사용 습관 skill이 함께 설치됩니다.
+
+```
+/plugin marketplace add jee1/memento
+/plugin install memento@memento
+```
+
+기억 DB는 `${CLAUDE_PLUGIN_DATA}/memory.db`에 저장되어 플러그인을 업데이트해도 유지됩니다. 설치 후 `/plugin` 패널에서 `memento` MCP 서버가 연결됐는지 확인하세요.
+
+### MCP 공식 레지스트리
+
+Memento는 MCP 공식 레지스트리에 `io.github.jee1/memento-mcp-server` 이름으로 등재됩니다. 레지스트리를 읽는 클라이언트·마켓플레이스에서 이 이름으로 찾을 수 있습니다.
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jee1/memento-mcp-server"
+```
+
+등재 메타데이터는 루트 [`server.json`](server.json)에 있고, 정식 릴리스마다 `release.yml`이 npm 배포 후 버전을 맞춰 자동으로 갱신합니다 (pre-release는 등재하지 않습니다).
+
 ### Docker 방식 (프로덕션용)
 ```bash
 docker-compose -f docker-compose.dev.yml up -d   # 개발
@@ -138,7 +168,7 @@ npm run build && npm run start:http       # 프로덕션
 
 OpenClaw / NanoClaw / ZeroClaw 같은 개인 AI 비서가 Memento를 공유 장기 기억 백엔드로 사용할 수 있습니다. 가이드: [docs/integrations/](./docs/integrations/README.md)
 
-`@memento/assistant` SDK를 사용하면 자동 recall/remember를 코드 두 줄로 붙일 수 있습니다 — [SDK quickstart](./docs/integrations/_shared/sdk-quickstart.md)
+`@jee1/memento-assistant` SDK를 사용하면 자동 recall/remember를 코드 두 줄로 붙일 수 있습니다 — [SDK quickstart](./docs/integrations/_shared/sdk-quickstart.md)
 
 ## 💡 사용 예시
 
@@ -199,7 +229,7 @@ await client.callTool({
 
 - **mcp.json 설정**: Claude Desktop, Cursor, Claude Code 등 MCP 호스트에 Memento를 등록하는 방식 (코드 불필요)
 - **MCP 프로토콜** (`@modelcontextprotocol/sdk`): 커스텀 에이전트 코드에서 MCP 프로토콜로 직접 연결하는 방식
-- **HTTP API 클라이언트** (`@memento/client`): TypeScript/JavaScript 코드에서 Memento 서버의 REST API를 프로그래밍 방식으로 사용하는 방식
+- **HTTP API 클라이언트** (`@jee1/memento-client`): TypeScript/JavaScript 코드에서 Memento 서버의 REST API를 프로그래밍 방식으로 사용하는 방식
 
 ### 0. mcp.json 설정 (Claude Desktop · Cursor · Claude Code)
 
@@ -308,12 +338,12 @@ const results = await client.callTool({
 });
 ```
 
-### 2. HTTP API 클라이언트 (`@memento/client`)
+### 2. HTTP API 클라이언트 (`@jee1/memento-client`)
 
-`@memento/client`는 MCP 프로토콜이 아닌 **HTTP REST API 래퍼**입니다. TypeScript/JavaScript 애플리케이션에서 `/tools/*` 엔드포인트를 직접 호출할 때 사용합니다.
+`@jee1/memento-client`는 MCP 프로토콜이 아닌 **HTTP REST API 래퍼**입니다. TypeScript/JavaScript 애플리케이션에서 `/tools/*` 엔드포인트를 직접 호출할 때 사용합니다.
 
 ```typescript
-import { MementoClient } from "@memento/client";
+import { MementoClient } from "@jee1/memento-client";
 
 const client = new MementoClient({
   serverUrl: "http://localhost:9001",
@@ -405,9 +435,11 @@ http://localhost:9001/graph
 
 ## 📋 API 문서
 
-### MCP Tools (핵심 22개)
+### MCP Tools (등록 22개, 기본 노출 4개)
 
-> **중요**: MCP 클라이언트는 핵심 메모리·관계·텔레메트리 도구 22개를 노출합니다. 관리/운영성 기능(앵커 복원, 임베딩 마이그레이션, Episodic→Semantic 변환, 메타 메모리 통계)은 HTTP API로만 제공됩니다.
+> **중요**: 서버에는 도구 22개가 등록되어 있지만, `tools/list`에는 기본적으로 **`recall`·`remember`·`memory_injection`·`feedback` 4개만** 노출됩니다(v1.18+). 도구 정의는 세션 내내 클라이언트 컨텍스트를 점유하므로, 늘 켜두는 서버일수록 기본 표면을 줄이는 편이 낫습니다(측정: 5,860 → 2,954 추정 토큰, 49.6% 감소).
+>
+> 나머지 18개는 **등록된 채로 남아 호출은 그대로 됩니다** — 목록에서만 빠집니다. 전부 나열하려면 `MEMENTO_TOOLSET=full`을 설정하세요. 관리/운영성 기능(앵커 복원, 임베딩 마이그레이션, Episodic→Semantic 변환, 메타 메모리 통계)은 여전히 HTTP API로만 제공됩니다.
 
 #### 기본 메모리 관리 (8개)
 | Tool | 설명 | 파라미터 |
@@ -581,6 +613,8 @@ npm run test -- --watch
 npm run test -- --coverage
 ```
 
+공개 데이터셋(LongMemEval-S·LoCoMo)으로 검색 품질을 재는 하네스는 `npm run quality:longmemeval:acquire`·`npm run quality:locomo:acquire`로 데이터를 받은 뒤 `npm run quality:locomo:benchmark`로 돌립니다. 원본 데이터는 커밋하지 않으며, LoCoMo는 **CC BY-NC 4.0(비상업)** 이라 상업적 사용이 불가합니다. 절차와 현재 수치는 [benchmark-datasets.md](docs/_work/testing/ko/benchmark-datasets.md)에 있고, 프로덕션 검색이 단순 FTS 베이스라인을 넘지 못한 상태라 대외 수치로 쓰지 않습니다.
+
 ## 📚 개발자 가이드라인
 
 - **프로젝트 구조**: npm workspaces 모노레포 — `packages/memento-core`, `packages/memento-server`, `packages/memento-client`, `apps/*`. 상세: [AGENTS.md](AGENTS.md)
@@ -613,7 +647,7 @@ npm run test -- --coverage
 
 Memento는 개인용 로컬 서버로 시작해, 팀 협업을 거쳐, 조직 규모의 메모리 플랫폼으로 성장하도록 설계되어 있다.
 
-**M1: 개인용 (현재)** — 지금 사용할 수 있는 형태다. SQLite 임베디드, FTS5 + sqlite-vec 인덱스, 로컬 실행. **인증**: 브라우저 세션 + 헤더 기반 분리 신뢰 모델(`/auth/session` 쿠키 세션, `/admin`·`/api` 브라우저 세션 요구, `/tools`·`/mcp`는 Bearer/API-Key 요구). 22개 MCP 도구, 관리 기능은 HTTP API로 분리.
+**M1: 개인용 (현재)** — 지금 사용할 수 있는 형태다. SQLite 임베디드, FTS5 + sqlite-vec 인덱스, 로컬 실행. **인증**: 브라우저 세션 + 헤더 기반 분리 신뢰 모델(`/auth/session` 쿠키 세션, `/admin`·`/api` 브라우저 세션 요구, `/tools`·`/mcp`는 Bearer/API-Key 요구). MCP 도구 22개 등록·기본 노출 4개(`MEMENTO_TOOLSET=full`로 전체), 관리 기능은 HTTP API로 분리.
 
 **M2: 팀 협업 (계획)** — SQLite 서버 모드, API Key 인증, Docker 단일 컨테이너. 여러 팀원이 하나의 기억 백엔드를 공유한다.
 
@@ -667,7 +701,7 @@ npm run test
 
 ## 📄 라이선스
 
-MIT 라이선스. 자세한 내용은 `LICENSE` 파일을 참조하세요.
+이 프로젝트는 [MIT License](LICENSE) 하에 배포됩니다. `package.json`의 `"license": "MIT"` 와 동일합니다.
 
 ## 📞 지원
 

package/dist/server/handlers/anchor-map.handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor-map.handler.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/anchor-map.handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAGpC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,kBAAkB,EAAE,CAa9E;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC,CAmCxB;AAgKD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,GAAG,CAAC,SAAS,CAAC,EAC3B,UAAU,EAAE,aAAa,GACxB,IAAI,CAeN;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,EAC5B,cAAc,EAAE,cAAc,GAAG,IAAI,EACrC,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,EACjD,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA2Bf"}
+{"version":3,"file":"anchor-map.handler.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/anchor-map.handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAGpC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,kBAAkB,EAAE,CAa9E;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC,CAoCxB;AAoPD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,GAAG,CAAC,SAAS,CAAC,EAC3B,UAAU,EAAE,aAAa,GACxB,IAAI,CAeN;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,EAC5B,cAAc,EAAE,cAAc,GAAG,IAAI,EACrC,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,EACjD,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/dist/server/handlers/anchor-map.handler.js

@@ -41,7 +41,7 @@ export async function buildAnchorMapData(db, serverServices, agentId) {
     }
     const anchorList = Array.isArray(anchors) ? anchors : [anchors];
     // 네트워크 노드 및 링크 생성
-    const { nodes, links } = await buildNetworkNodesAndLinks(db, anchorManager, agentId, anchorList);
+    const { nodes, links } = await buildNetworkNodesAndLinks(db, anchorManager, agentId, anchorList, serverServices.relationGraph);
     return {
         agent_id: agentId,
         anchors: anchorList,
@@ -50,13 +50,67 @@ export async function buildAnchorMapData(db, serverServices, agentId) {
         timestamp: new Date().toISOString()
     };
 }
+/**
+ * 검색 결과 항목이 가리키는 predecessor id 목록을 얻는다.
+ * n-hop 검색이 여러 경로로 같은 메모리를 재발견하면 predecessor_ids(복수)에 모두 기록되므로
+ * (#715 MEDIUM#1), 있으면 그것을 우선하고 없으면 predecessor_id(단수)로 대체한다.
+ */
+function getPredecessorIds(item) {
+    const ids = item.predecessor_ids;
+    if (Array.isArray(ids)) {
+        return ids.filter((id) => typeof id === 'string');
+    }
+    return typeof item.predecessor_id === 'string' ? [item.predecessor_id] : [];
+}
+/**
+ * hop 오름차순으로 경로 폐쇄성(path-closure)을 검증하며 노드/엣지를 확정한다.
+ * predecessor가 랭킹/limit/쿼리 필터로 탈락해 경로가 끊긴 hop≥2 노드는
+ * 부유(floating) 상태로 지도에 남기지 않고 제외한다 (#715 MEDIUM#2).
+ */
+function resolvePathClosedItems(items, anchorMemoryId) {
+    const itemsByHop = new Map();
+    for (const item of items) {
+        const hop = typeof item.hop_distance === 'number' ? item.hop_distance : 0;
+        const bucket = itemsByHop.get(hop) ?? [];
+        bucket.push(item);
+        itemsByHop.set(hop, bucket);
+    }
+    const reachableIds = new Set([anchorMemoryId]);
+    const reachableItems = [];
+    const edges = [];
+    const hopsAscending = Array.from(itemsByHop.keys())
+        .filter(hop => hop >= 1)
+        .sort((a, b) => a - b);
+    for (const hop of hopsAscending) {
+        for (const item of itemsByHop.get(hop) ?? []) {
+            if (hop === 1) {
+                reachableIds.add(item.id);
+                reachableItems.push(item);
+                edges.push({ source: anchorMemoryId, target: item.id, hop_distance: 1, similarity: item.similarity });
+                continue;
+            }
+            const validPredecessorIds = getPredecessorIds(item).filter(id => reachableIds.has(id));
+            if (validPredecessorIds.length === 0) {
+                continue; // 경로가 끊긴 노드는 지도에 포함하지 않음
+            }
+            reachableIds.add(item.id);
+            reachableItems.push(item);
+            for (const predecessorId of validPredecessorIds) {
+                edges.push({ source: predecessorId, target: item.id, hop_distance: hop, similarity: item.similarity });
+            }
+        }
+    }
+    return { reachableItems, edges };
+}
 /**
  * 네트워크 노드 및 링크 생성
  */
-async function buildNetworkNodesAndLinks(db, anchorManager, agentId, anchorList) {
+async function buildNetworkNodesAndLinks(db, anchorManager, agentId, anchorList, relationGraph) {
     const nodes = [];
     const links = [];
-    const processedMemoryIds = new Set();
+    // 노드 dedup(메모리 id당 1개)과 별개로, slot→memory 엣지는 슬롯마다 생성한다
+    // (같은 메모리가 slot A/B에 모두 잡히면 노드는 1개, 엣지는 2개)
+    const nodeIds = new Set();
     // 각 앵커에 대해 처리
     for (const anchor of anchorList) {
         if (!anchor.memory_id)
@@ -68,44 +122,52 @@ async function buildNetworkNodesAndLinks(db, anchorManager, agentId, anchorList)
       WHERE id = ?
     `).get(anchor.memory_id);
         if (anchorMemory) {
-            nodes.push({
-                id: anchor.memory_id,
-                type: 'anchor',
-                slot: anchor.slot,
-                content: anchorMemory.content.substring(0, 100),
-                importance: anchorMemory.importance,
-                created_at: anchorMemory.created_at
-            });
-            processedMemoryIds.add(anchor.memory_id);
+            if (!nodeIds.has(anchor.memory_id)) {
+                nodes.push({
+                    id: anchor.memory_id,
+                    type: 'anchor',
+                    slot: anchor.slot,
+                    content: anchorMemory.content.substring(0, 100),
+                    importance: anchorMemory.importance,
+                    created_at: anchorMemory.created_at
+                });
+                nodeIds.add(anchor.memory_id);
+            }
             // 앵커 주변 메모리 검색
             try {
                 const slotConfig = anchorManager.getSlotConfig(anchor.slot);
                 const searchResult = await anchorManager.searchLocal(agentId, anchor.slot, undefined, slotConfig.hop_limit, { limit: 50 });
-                // 검색 결과를 노드와 링크로 변환
-                for (const item of searchResult.items) {
-                    if (processedMemoryIds.has(item.id))
-                        continue;
-                    nodes.push({
-                        id: item.id,
-                        type: 'memory',
-                        content: item.content.substring(0, 100),
-                        hop_distance: item.hop_distance || 0,
-                        similarity: item.similarity,
-                        importance: item.importance,
-                        created_at: item.created_at
-                    });
-                    processedMemoryIds.add(item.id);
-                    // 링크 추가 (앵커에서 메모리로)
-                    if (item.hop_distance === 1) {
-                        links.push({
-                            source: anchor.memory_id,
-                            target: item.id,
-                            type: 'hop',
-                            hop_distance: 1,
-                            similarity: item.similarity
+                const anchorNode = nodes.find(n => n.id === anchor.memory_id);
+                if (anchorNode && searchResult.anchor_info?.embedding_missing) {
+                    anchorNode.embedding_missing = true;
+                }
+                // hop 오름차순으로 경로 폐쇄성을 검증해, predecessor가 랭킹/limit/쿼리 필터로
+                // 탈락한 hop≥2 노드는 부유(floating) 상태로 남기지 않고 제외한다 (#715 MEDIUM#2).
+                // 노드 dedup과 별개로, 하나의 메모리로 여러 경로가 합류하면 edge는 모두 보존한다 (#715 MEDIUM#1).
+                const { reachableItems, edges } = resolvePathClosedItems(searchResult.items, anchor.memory_id);
+                for (const item of reachableItems) {
+                    if (!nodeIds.has(item.id)) {
+                        nodes.push({
+                            id: item.id,
+                            type: 'memory',
+                            content: item.content.substring(0, 100),
+                            hop_distance: item.hop_distance || 0,
+                            similarity: item.similarity,
+                            importance: item.importance,
+                            created_at: item.created_at
                         });
+                        nodeIds.add(item.id);
                     }
                 }
+                for (const edge of edges) {
+                    links.push({
+                        source: edge.source,
+                        target: edge.target,
+                        type: 'hop',
+                        hop_distance: edge.hop_distance,
+                        similarity: edge.similarity
+                    });
+                }
             }
             catch (error) {
                 const isEmbeddingMissing = error instanceof Error && error.name === 'EmbeddingNotFoundError';
@@ -123,48 +185,53 @@ async function buildNetworkNodesAndLinks(db, anchorManager, agentId, anchorList)
                         slot: anchor.slot,
                         error: error instanceof Error ? error.message : String(error)
                     });
+                    throw error;
                 }
             }
         }
     }
-    // memory_link 테이블을 활용한 직접 연결 정보 추가
-    const memoryLinks = buildNetworkLinks(db, nodes, processedMemoryIds);
-    links.push(...memoryLinks);
+    // memory_relation 테이블(RelationGraph)을 활용한 직접 연결 정보 추가
+    const relationLinks = await buildRelationLinks(relationGraph, nodeIds);
+    links.push(...relationLinks);
     return { nodes, links };
 }
 /**
- * memory_link 테이블을 활용한 네트워크 링크 생성
+ * RelationGraph(memory_relation)를 활용한 네트워크 링크 생성.
+ * 노드로 등록된 메모리끼리의 관계만 엣지로 반영하며, confidence를 가중치로 사용한다.
+ * hop 2/3의 anchor→memory 경로 엣지는 buildNetworkNodesAndLinks에서
+ * n-hop 검색 결과의 predecessor_id로 생성하므로(#715) 이 함수는 다루지 않는다.
  */
-function buildNetworkLinks(db, nodes, processedMemoryIds) {
+async function buildRelationLinks(relationGraph, nodeIds) {
     const links = [];
-    for (const node of nodes) {
-        if (node.type === 'anchor')
-            continue;
-        // memory_link 테이블 조회
-        const linkedMemories = db.prepare(`
-      SELECT target_id, relation_type, created_at
-      FROM memory_link
-      WHERE source_id = ?
-      UNION
-      SELECT source_id, relation_type, created_at
-      FROM memory_link
-      WHERE target_id = ?
-    `).all(node.id, node.id);
-        for (const link of linkedMemories) {
-            const linkedId = link.target_id || link.source_id;
-            if (linkedId && processedMemoryIds.has(linkedId)) {
-                // relation_type을 기반으로 similarity 추정
-                const similarity = link.relation_type === 'derived_from' ? 0.9 :
-                    link.relation_type === 'cause_of' ? 0.8 : 0.7;
+    if (nodeIds.size === 0)
+        return links;
+    const memoryIds = Array.from(nodeIds);
+    try {
+        const relationsByMemory = await relationGraph.getRelationsBatch(memoryIds, { direction: 'both' });
+        const seenRelationIds = new Set();
+        for (const memoryId of memoryIds) {
+            for (const relation of relationsByMemory.get(memoryId) ?? []) {
+                if (seenRelationIds.has(relation.id))
+                    continue;
+                const otherId = relation.source_id === memoryId ? relation.target_id : relation.source_id;
+                if (otherId === memoryId || !nodeIds.has(otherId))
+                    continue;
+                seenRelationIds.add(relation.id);
                 links.push({
-                    source: node.id,
-                    target: linkedId,
+                    source: relation.source_id,
+                    target: relation.target_id,
                     type: 'link',
-                    similarity: similarity
+                    similarity: relation.confidence
                 });
             }
         }
     }
+    catch (error) {
+        logger.error('Relation link lookup failed', {
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
     return links;
 }
 /**