memento-mcp-server 1.26.0 → 1.27.0-a

package/README.en.md

@@ -298,10 +298,10 @@ npm run test -- --coverage
 ## 📚 Developer Guidelines
 
 ### Repository Guidelines (`AGENTS.md`)
-- **Project Structure**: Module organization under `src/`
+- **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 based, `src/test/` or `*.spec.ts` files
+- **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
 

package/README.md

@@ -262,69 +262,160 @@ await client.callTool({
 
 ## 🛠️ 사용법
 
-### MCP 클라이언트 연결
+> **접근 방식 세 가지**:
+> - **mcp.json 설정**: Claude Desktop, Cursor, Claude Code 등 MCP 호스트에 Memento를 등록하는 방식 (코드 불필요)
+> - **MCP 프로토콜** (`@modelcontextprotocol/sdk`): 커스텀 에이전트 코드에서 MCP 프로토콜로 직접 연결하는 방식
+> - **HTTP API 클라이언트** (`@memento/client`): TypeScript/JavaScript 코드에서 Memento 서버의 REST API를 프로그래밍 방식으로 사용하는 방식
+
+### 0. mcp.json 설정 (Claude Desktop · Cursor · Claude Code)
+
+MCP 호스트 앱에서 Memento를 사용하려면 설정 파일에 서버 정보를 등록합니다.
+
+#### stdio 모드 (단일 에이전트 / 소스 실행)
+
+`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"
+      }
+    }
+  }
+}
+```
+
+> **파일 위치**:
+> - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+> - Cursor: `.cursor/mcp.json` (프로젝트) 또는 `~/.cursor/mcp.json` (전역)
+> - Claude Code: `.claude/mcp.json` (프로젝트) 또는 `~/.claude/mcp.json` (전역)
+
+#### HTTP MCP 모드 (다중 에이전트 공유 서버)
+
+여러 에이전트가 동일한 서버에 접속할 때 사용합니다. 먼저 서버를 띄운 뒤 등록합니다.
+
+```bash
+# 서버 먼저 실행
+npm run build && npm run start:http   # 기본 포트: 8080
+```
+
+```json
+{
+  "mcpServers": {
+    "memento": {
+      "type": "http",
+      "url": "http://127.0.0.1:8080/mcp"
+    }
+  }
+}
+```
+
+> **npx로 실행하는 경우** (소스 빌드 없이):
+> ```json
+> {
+>   "mcpServers": {
+>     "memento": {
+>       "command": "npx",
+>       "args": ["memento-mcp-server@latest"],
+>       "env": {
+>         "DB_PATH": "/absolute/path/to/data/memory.db"
+>       }
+>     }
+>   }
+> }
+> ```
+
+### 1. MCP 프로토콜 연결 (`@modelcontextprotocol/sdk`)
+
+MCP 호스트나 커스텀 에이전트에서 MCP 프로토콜로 직접 연결할 때 사용합니다.
 
 ```typescript
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
 const client = new Client({
-  name: "memento-client",
+  name: "my-agent",
   version: "0.1.0"
 }, {
-  capabilities: {
-    tools: {},
-    resources: {},
-    prompts: {}
-  }
+  capabilities: { tools: {}, resources: {}, prompts: {} }
 });
 
-// stdio 연결
+// stdio 연결 (단일 프로세스)
 await client.connect({
   command: "node",
   args: ["packages/memento-server/dist/server/index.js"]
 });
 
-// WebSocket 연결
+// HTTP MCP 연결 (다중 에이전트 공유 서버)
 await client.connect({
   transport: {
-    type: "websocket",
-    url: "ws://localhost:9001/mcp"
+    type: "http",
+    url: "http://127.0.0.1:7777"
   }
 });
 ```
 
-### 기억 저장
-
 ```typescript
-// 기억 저장
+// MCP 도구 호출
 const result = await client.callTool({
   name: "remember",
   arguments: {
-    content: "React Hook에 대해 학습했습니다. useState는 상태를 관리하고, useEffect는 사이드 이펙트를 처리합니다.",
+    content: "React Hook에 대해 학습했습니다.",
     type: "episodic",
-    tags: ["react", "hooks", "javascript"],
+    tags: ["react", "hooks"],
     importance: 0.8
   }
 });
-```
-
-### 기억 검색
 
-```typescript
-// 기억 검색
 const results = await client.callTool({
   name: "recall",
   arguments: {
     query: "React Hook을 처음 배울 때 알아야 할 것들은?",
-    filters: {
-      type: ["episodic", "semantic"],
-      tags: ["react"]
-    },
+    filters: { type: ["episodic", "semantic"], tags: ["react"] },
     limit: 10
   }
 });
 ```
 
+### 2. HTTP API 클라이언트 (`@memento/client`)
+
+`@memento/client`는 MCP 프로토콜이 아닌 **HTTP REST API 래퍼**입니다. TypeScript/JavaScript 애플리케이션에서 Memento 서버의 `/tools/*` 엔드포인트를 직접 호출할 때 사용합니다.
+
+```typescript
+import { MementoClient } from "@memento/client";
+
+const client = new MementoClient({
+  serverUrl: "http://localhost:8080",
+  apiKey: "your-api-key"       // HTTP 서버의 Bearer 토큰
+});
+
+await client.connect();        // /health 엔드포인트로 연결 확인
+```
+
+```typescript
+// 기억 저장
+const result = await client.remember({
+  content: "React Hook에 대해 학습했습니다.",
+  type: "episodic",
+  tags: ["react", "hooks"],
+  importance: 0.8
+});
+
+// 기억 검색
+const results = await client.recall(
+  "React Hook을 처음 배울 때 알아야 할 것들은?",
+  { type: ["episodic", "semantic"], tags: ["react"] },
+  10
+);
+
+// 기억 고정 / 삭제
+await client.pin(result.memory_id);
+await client.forget(result.memory_id);
+```
+
 ## 📚 문서
 
 - [임베딩 서비스 가이드](docs/guides/ko/embedding-service-guide.md) - 임베딩 서비스 사용법
@@ -500,7 +591,7 @@ npm run test -- --coverage
 - **프로젝트 구조**: npm workspaces 모노레포 — `packages/memento-core`, `packages/memento-server`, `packages/memento-client`, `apps/*`. 서버 코드는 `packages/memento-server`, 도메인·인프라는 `packages/memento-core`.
 - **빌드/테스트 명령어**: `npm run build`(core→server→client), `npm run dev`·`npm start`(서버), `npm run db:init`·`npm run db:migrate`(DB), `npm test` 등. 상세는 [AGENTS.md](AGENTS.md) 참조.
 - **코딩 스타일**: Node.js ≥ 24, TypeScript ES 모듈, 2칸 들여쓰기
-- **테스트 가이드라인**: Vitest 기반, 각 패키지 `src/` 내 `*.spec.ts` 또는 루트 `src/test/`
+- **테스트 가이드라인**: Vitest 기반. 단위·스펙은 주로 `packages/memento-core/src/**`, `packages/memento-server/src/**` 등 패키지 트리의 `*.spec.ts`에 두고, 루트 `tests/`에는 워크스페이스 수준 통합 스펙이 있다.
 - **커밋/PR 가이드라인**: Conventional Commits, 한국어 컨텍스트 포함
 - **환경/데이터베이스**: `.env` 설정, `data/` 폴더 관리
 

package/dist/cli/agent-ask.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `memento agent ask` — in-process 개인 지식 Agent 한 턴 (#236).
+ * 설계: docs/superpowers/specs/2026-05-14-issue-236-agent-ask-cli-design.md
+ * 테스트 훅: `AgentAskRuntimeHooks` (#237, Vitest에서 stdin/승인 주입).
+ */
+import type { KnowledgeCandidate } from '@memento/core';
+export type PreCliOptions = {
+    dbPath?: string;
+    envFile?: string;
+    configDir?: string;
+};
+/** argv[2..]에서 글로벌 CLI 쌍 제거 (cli.ts와 동일 3종). */
+export declare function stripGlobalCliArgs(argv: string[]): string[];
+export type ParsedAgentAsk = {
+    kind: 'help';
+} | {
+    kind: 'usage';
+    message: string;
+} | {
+    kind: 'run';
+    userMessage: string;
+    projectId?: string;
+    tokenBudget?: number;
+    json: boolean;
+    noSave: boolean;
+    /** `--json`만 있고 `--no-save`는 없을 때 true — stderr 안내 한 줄 출력 */
+    jsonImplicitNoSave: boolean;
+    /** `--llm mock`이면 환경 변수 provider보다 mock을 우선한다. */
+    forceLlmMock: boolean;
+};
+/**
+ * `memento … agent ask …` 패턴 파싱. `ask` 직후 첫 토큰이 userMessage(플래그 아님).
+ */
+export declare function parseAgentAskInvocation(argv: string[]): ParsedAgentAsk;
+export declare function validateAgentAskFlagArgv(flagArgv: string[]): string | null;
+export declare function validateAgentAskRawTypes(raw: Record<string, unknown>): string | null;
+export type AgentAskApproveAnswer = 'y' | 'n' | 's' | 'q' | 'interrupt';
+/** 기본 readline 승인 프롬프트. 테스트에서는 `AgentAskRuntimeHooks.promptApprove`로 대체 가능 (#237). */
+export declare function promptApproveInteractive(candidate: KnowledgeCandidate, index: number, total: number, interruptRef: {
+    interrupted: boolean;
+}): Promise<AgentAskApproveAnswer>;
+export type AgentAskPromptApprove = (candidate: KnowledgeCandidate, index: number, total: number, interruptRef: {
+    interrupted: boolean;
+}) => Promise<AgentAskApproveAnswer>;
+/** in-process 테스트 전용: 제품 CLI 경로는 `cli.ts`가 훅 없이 호출한다 (#237). */
+export interface AgentAskRuntimeHooks {
+    /** 미지정 시 `process.stdin.isTTY` */
+    stdinIsTTY?: boolean;
+    /** 미지정 시 `promptApproveInteractive` */
+    promptApprove?: AgentAskPromptApprove;
+}
+export declare function runAgentAskMain(preOptions: PreCliOptions, argv: string[], hooks?: AgentAskRuntimeHooks): Promise<number>;
+export declare function agentAskHelpText(): string;
+//# sourceMappingURL=agent-ask.d.ts.map

package/dist/cli/agent-ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-ask.d.ts","sourceRoot":"","sources":["../../src/cli/agent-ask.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqBH,OAAO,KAAK,EAAY,kBAAkB,EAAsC,MAAM,eAAe,CAAC;AAQtG,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAW3D;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,6DAA6D;IAC7D,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kDAAkD;IAClD,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEN;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CAgFtE;AAaD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CA4B1E;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAkBpF;AAkDD,MAAM,MAAM,qBAAqB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,WAAW,CAAC;AAExE,sFAAsF;AACtF,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,kBAAkB,EAC7B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,YAAY,EAAE;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,GACrC,OAAO,CAAC,qBAAqB,CAAC,CA+BhC;AAED,MAAM,MAAM,qBAAqB,GAAG,CAClC,SAAS,EAAE,kBAAkB,EAC7B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,YAAY,EAAE;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,KACnC,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAEpC,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACvC;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,CAAC,EAAE,oBAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAwTjB;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAezC"}