ralph-mem 0.1.0 → 0.1.3

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "ralph-mem",
+  "description": "Ralph Loop 기반 반복 실행 및 세션 간 컨텍스트 영속성 관리",
+  "version": "0.1.0",
+  "author": {
+    "name": "roboco-io"
+  },
+  "homepage": "https://github.com/roboco-io/ralph-mem",
+  "repository": "https://github.com/roboco-io/ralph-mem",
+  "license": "MIT"
+}

package/README.md

@@ -1,10 +1,17 @@
 # ralph-mem
 
+[![npm version](https://img.shields.io/npm/v/ralph-mem.svg)](https://www.npmjs.com/package/ralph-mem)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
+
 Claude Code를 위한 Ralph Loop 기반 지속적 컨텍스트 관리 플러그인
 
 ## 개요
 
-ralph-mem은 [Ralph Loop](https://ghuntley.com/ralph/)의 "성공할 때까지 반복" 철학과 [claude-mem](https://github.com/thedotmack/claude-mem)의 "지능적 컨텍스트 관리"를 결합한 Claude Code 플러그인입니다.
+ralph-mem은 [Geoffrey Huntley](https://ghuntley.com/)의 [Ralph Loop](https://ghuntley.com/ralph/)와 [thedotmack](https://github.com/thedotmack)의 [claude-mem](https://github.com/thedotmack/claude-mem)에서 영감을 받아 시작된 프로젝트입니다.
+
+Ralph Loop의 "성공할 때까지 반복" 철학과 claude-mem의 "지능적 컨텍스트 관리"를 결합하여 Claude Code를 위한 지속적 메모리 관리 플러그인을 구현했습니다.
 
 ### 해결하는 문제
 
@@ -60,6 +67,7 @@ flowchart TB
 
 - `SessionStart` - 관련 메모리 자동 주입
 - `PostToolUse` - 도구 사용 결과 기록
+- `Stop` - 세션 강제 종료 시 정리 작업
 - `SessionEnd` - 세션 요약 생성 및 저장
 
 ### 3. Progressive Disclosure
@@ -79,11 +87,63 @@ flowchart TB
 
 ## 설치
 
+### npm
+
+```bash
+npm install ralph-mem
+```
+
+### yarn
+
+```bash
+yarn add ralph-mem
+```
+
+### pnpm
+
 ```bash
-# Claude Code 플러그인으로 설치
-claude plugins install ralph-mem
+pnpm add ralph-mem
+```
+
+### bun
+
+```bash
+bun add ralph-mem
+```
+
+### Claude Code 플러그인
+
+Claude Code에서 플러그인으로 사용하려면 [roboco-io/plugins](https://github.com/roboco-io/plugins) 마켓플레이스를 통해 설치합니다:
+
+1. 마켓플레이스 추가
+```
+/plugin marketplace add roboco-io/plugins
+```
+
+2. 플러그인 설치
+```
+/plugin install ralph-mem@roboco-plugins
 ```
 
+또는 `/plugin` 명령으로 플러그인 매니저를 열어 UI에서 설치할 수 있습니다.
+
+### 플러그인 업데이트
+
+방법 1: CLI 명령으로 업데이트 (터미널에서 실행)
+```
+claude plugin update ralph-mem@roboco-plugins
+```
+
+방법 2: 재설치 (세션 내에서 실행)
+```
+/plugin uninstall ralph-mem
+```
+```
+/plugin install ralph-mem@roboco-plugins
+```
+
+업데이트 후 Claude Code를 재시작하면 변경 사항이 적용됩니다.
+
 ## 사용법
 
 ### Ralph Loop
@@ -128,6 +188,38 @@ claude plugins install ralph-mem
 /mem-forget <observation-id>
 ```
 
+### 4. Privacy 기능
+
+민감한 정보를 메모리에서 제외합니다.
+
+**`<private>` 태그:**
+
+```bash
+# 태그로 감싼 내용은 저장되지 않습니다
+My API key is <private>sk-1234567890</private>
+# 저장됨: My API key is [PRIVATE]
+```
+
+**설정 기반 제외:**
+
+```yaml
+privacy:
+  exclude_patterns:
+    - "*.env"
+    - "*password*"
+    - "*secret*"
+```
+
+### 5. MCP 도구
+
+스킬 외에 MCP(Model Context Protocol) 도구로도 메모리에 접근할 수 있습니다.
+
+| 도구 | 설명 |
+|------|------|
+| `ralph_mem_search` | Progressive Disclosure 기반 검색 |
+| `ralph_mem_timeline` | 특정 관찰 주변 시간순 컨텍스트 |
+| `ralph_mem_get` | 관찰 ID로 전체 상세 조회 |
+
 ## 설정
 
 `~/.config/ralph-mem/config.yaml`:
@@ -153,6 +245,144 @@ privacy:
     - "*secret*"
 ```
 
+## 동작 원리
+
+ralph-mem은 크게 두 가지 모드로 동작합니다:
+
+1. **자동 모드 (Lifecycle Hooks)**: 사용자 개입 없이 백그라운드에서 동작
+2. **명시적 모드 (Skills/Commands)**: 사용자가 슬래시 명령어로 직접 제어
+
+### Lifecycle Hooks
+
+플러그인이 설치되면 Claude Code의 lifecycle에 자동으로 연결되어 동작합니다.
+
+```mermaid
+sequenceDiagram
+    participant CC as Claude Code
+    participant Hook as Hook Layer
+    participant Core as Core Layer
+    participant DB as SQLite
+
+    CC->>Hook: SessionStart
+    Hook->>Core: 관련 메모리 검색
+    Core->>DB: FTS5 + Embedding 검색
+    DB-->>Core: 이전 컨텍스트
+    Core-->>Hook: 검색 결과
+    Hook-->>CC: 컨텍스트 자동 주입
+
+    CC->>Hook: UserPromptSubmit
+    Hook->>Core: 쿼리 관련 검색
+    Core-->>Hook: 관련 메모리 알림
+    Hook-->>CC: 알림 표시 (주입 X)
+
+    CC->>Hook: PostToolUse
+    Hook->>Core: 도구 사용 결과 기록
+    Core->>DB: Observation 저장
+
+    CC->>Hook: SessionEnd
+    Hook->>Core: 세션 요약 생성
+    Core->>DB: 요약 저장
+```
+
+| Hook | 시점 | 동작 |
+|------|------|------|
+| `SessionStart` | 세션 시작 | 프로젝트 관련 이전 컨텍스트 자동 주입 |
+| `UserPromptSubmit` | 프롬프트 제출 | 관련 메모리 알림 (토큰 절약을 위해 주입하지 않음) |
+| `PostToolUse` | 도구 사용 후 | 쓰기 도구, Bash 명령 결과를 Observation으로 기록 |
+| `SessionEnd` | 세션 종료 | 세션 요약 생성 및 저장 |
+
+### Ralph Loop 동작
+
+`/ralph start` 명령으로 활성화되며, 성공 기준 달성까지 자동 반복합니다.
+
+```mermaid
+flowchart LR
+    A[Task + Context] --> B[Claude 실행]
+    B --> C{성공 판단}
+    C -->|YES| D[완료]
+    C -->|NO| E[결과 추가]
+    E --> F{중단 조건?}
+    F -->|NO| A
+    F -->|YES| G[실패 + 롤백 안내]
+```
+
+**성공 판단**: Claude가 테스트/빌드 출력을 분석하여 성공 여부를 판단합니다.
+
+**Overbaking 방지**: 무한 반복을 방지하기 위한 중단 조건:
+
+| 조건 | 기본값 | 설명 |
+|------|--------|------|
+| `maxIterations` | 10 | 최대 반복 횟수 |
+| `maxDurationMs` | 30분 | 최대 실행 시간 |
+| `noProgressThreshold` | 3회 | 진척 없음 허용 횟수 |
+
+**스냅샷**: Loop 시작 시 변경 파일을 스냅샷으로 저장하여 실패 시 롤백 가능.
+
+### 검색 엔진
+
+2단계 검색으로 최적의 결과를 반환합니다:
+
+1. **FTS5 전문 검색** (기본): SQLite FTS5를 사용한 빠른 텍스트 검색
+2. **Embedding 유사도** (폴백): FTS5 결과가 부족할 때 의미 기반 검색
+
+**Embedding 모델**: `paraphrase-multilingual-MiniLM-L12-v2`
+- 로컬 실행 (API 호출 없음)
+- 50+ 언어 지원 (한국어, 영어 포함)
+- 384차원, ~278MB
+
+### 데이터 흐름
+
+```mermaid
+flowchart TB
+    subgraph Input["입력"]
+        Tool[도구 사용 결과]
+        Prompt[사용자 프롬프트]
+    end
+
+    subgraph Process["처리"]
+        Privacy[Privacy 필터]
+        Compress[압축기]
+        Embed[Embedding 생성]
+    end
+
+    subgraph Storage["저장"]
+        Obs[(Observations)]
+        Session[(Sessions)]
+        FTS[(FTS5 Index)]
+        Vec[(Embedding)]
+    end
+
+    Tool --> Privacy
+    Privacy --> Compress
+    Compress --> Obs
+    Obs --> FTS
+    Obs --> Embed
+    Embed --> Vec
+
+    Prompt --> FTS
+    Prompt --> Vec
+    FTS --> Result[검색 결과]
+    Vec --> Result
+```
+
+### Observation 타입
+
+도구 사용 결과는 타입별로 분류되어 저장됩니다:
+
+| 타입 | 설명 | 기록 대상 |
+|------|------|----------|
+| `tool_use` | 도구 사용 결과 | Edit, Write 등 쓰기 도구 |
+| `bash` | 명령 실행 결과 | Bash 명령어 |
+| `error` | 에러 발생 | 모든 에러 (높은 중요도) |
+| `success` | 성공 기록 | 테스트 통과, 빌드 성공 |
+| `note` | 수동 메모 | `/mem-inject`로 주입된 내용 |
+
+**중요도 자동 산정**:
+- 에러 발생: 1.0 (최고)
+- 테스트 통과/실패: 0.9
+- 파일 생성/수정: 0.7
+- 일반 명령: 0.5
+
 ## 아키텍처
 
 ```mermaid

package/commands/mem-forget.md

@@ -0,0 +1,17 @@
+---
+description: 특정 메모리 항목 삭제
+---
+
+# Memory Forget
+
+특정 메모리 항목을 삭제합니다.
+
+## 사용법
+
+- `obs-id` - 특정 관찰 삭제
+- `--session sess-id` - 특정 세션의 모든 관찰 삭제
+- `--before 30d` - 30일 이전의 관찰 삭제
+- `--type error` - 특정 타입의 관찰만 삭제
+- `--dry-run` - 실제 삭제 없이 대상 확인
+
+$ARGUMENTS

package/commands/mem-inject.md

@@ -0,0 +1,23 @@
+---
+description: 수동으로 컨텍스트를 메모리에 주입
+---
+
+# Memory Inject
+
+수동으로 컨텍스트를 메모리에 저장합니다.
+
+## 사용법
+
+- `"context"` - 컨텍스트 저장
+- `"context" --type note` - 타입 지정하여 저장
+- `"context" --tags tag1,tag2` - 태그와 함께 저장
+
+## 관찰 타입
+
+- `note` - 일반 메모 (기본값)
+- `tool_use` - 도구 사용 기록
+- `bash` - 명령어 실행 기록
+- `error` - 에러 기록
+- `success` - 성공 기록
+
+$ARGUMENTS

package/commands/mem-search.md

@@ -0,0 +1,24 @@
+---
+description: 저장된 메모리 검색 (Progressive disclosure로 토큰 효율적 사용)
+---
+
+# Memory Search
+
+저장된 관찰 기록과 세션 정보를 검색합니다.
+
+## 사용법
+
+- `"keyword"` - 키워드로 검색 (Layer 1)
+- `"keyword" --layer 2` - 타임라인 컨텍스트 포함
+- `--layer 3 obs-id` - 특정 관찰의 전체 상세 정보
+- `"keyword" --since 7d` - 최근 7일 내 검색
+
+## 검색 레이어
+
+| Layer | 내용 | 토큰 |
+|-------|------|------|
+| 1 | Index (ID + 점수) | 50-100/결과 |
+| 2 | Timeline (시간순 컨텍스트) | 200-300/결과 |
+| 3 | Full Details | 500-1000/결과 |
+
+$ARGUMENTS

package/commands/mem-status.md

@@ -0,0 +1,23 @@
+---
+description: 메모리 상태와 통계 확인
+---
+
+# Memory Status
+
+메모리 시스템의 현재 상태를 확인합니다.
+
+## 사용법
+
+- (인수 없음) - 기본 상태 표시
+- `--detailed` - 상세 통계 표시
+- `--json` - JSON 형식으로 출력
+
+## 출력 정보
+
+- 총 세션 수
+- 총 관찰 수
+- 타입별 관찰 분포
+- 스토리지 사용량
+- 최근 활동
+
+$ARGUMENTS

package/commands/ralph.md

@@ -0,0 +1,26 @@
+---
+description: Ralph Loop 제어 - 성공할 때까지 반복 실행 (start, stop, status, config)
+---
+
+# Ralph Loop
+
+성공 기준을 달성할 때까지 작업을 자동으로 반복 실행합니다.
+
+## 사용법
+
+- `start "task"` - Loop 시작
+- `start "task" --criteria lint_clean` - 커스텀 성공 기준으로 시작
+- `stop` - Loop 중단
+- `stop --rollback` - 변경사항 롤백하며 중단
+- `status` - 현재 상태 확인
+- `config` - 설정 확인/변경
+
+## 성공 기준
+
+- `test_pass` - 테스트 통과 (기본값)
+- `build_success` - 빌드 성공
+- `lint_clean` - Lint 오류 없음
+- `type_check` - 타입 체크 통과
+- `custom` - 사용자 정의 명령
+
+$ARGUMENTS

package/dist/{chunk-v8anyhk1.js → chunk-gy7xx0jv.js}

@@ -1,6 +1,6 @@
 import {
   createDBClient
-} from "./chunk-41rc1bhg.js";
+} from "./chunk-jz140n5a.js";
 
 // src/core/store.ts
 function toSession(dbSession) {

package/dist/{chunk-41rc1bhg.js → chunk-jz140n5a.js}

@@ -69,7 +69,7 @@ var require_file_uri_to_path = __commonJS((exports, module) => {
 
 // node_modules/bindings/bindings.js
 var require_bindings = __commonJS((exports, module) => {
-  var __filename = "/Users/dohyunjung/Workspace/roboco-io/ralph-mem/node_modules/bindings/bindings.js";
+  var __filename = "/home/runner/work/ralph-mem/ralph-mem/node_modules/bindings/bindings.js";
   var fs = __require("fs");
   var path = __require("path");
   var fileURLToPath = require_file_uri_to_path();

package/dist/{chunk-kga64hvg.js → chunk-rcnembz5.js}

@@ -1,6 +1,6 @@
 import {
   createDBClient
-} from "./chunk-41rc1bhg.js";
+} from "./chunk-jz140n5a.js";
 
 // src/core/search.ts
 function escapeFtsQuery(query) {

package/dist/hooks/post-tool-use.js

@@ -3,13 +3,28 @@ import {
 } from "../chunk-c3a91ngd.js";
 import {
   createDBClient
-} from "../chunk-41rc1bhg.js";
+} from "../chunk-jz140n5a.js";
 import {
   ensureProjectDirs,
   getProjectDBPath
 } from "../chunk-w40c0y00.js";
 import"../chunk-ns0dgdnb.js";
 
+// src/utils/privacy.ts
+function stripPrivateTags(content) {
+  const privateTagRegex = /<private>[\s\S]*?<\/private>/gi;
+  return content.replace(privateTagRegex, "[PRIVATE]");
+}
+function isEntirelyPrivate(content) {
+  const trimmed = content.trim();
+  const fullPrivateRegex = /^<private>[\s\S]*<\/private>$/i;
+  if (fullPrivateRegex.test(trimmed)) {
+    const stripped = stripPrivateTags(trimmed);
+    return stripped.trim() === "[PRIVATE]";
+  }
+  return false;
+}
+
 // src/hooks/post-tool-use.ts
 var RECORDABLE_TOOLS = new Set([
   "Edit",
@@ -97,6 +112,15 @@ async function postToolUseHook(context, options) {
     content = `Error: ${context.error}
 ${content}`;
   }
+  if (isEntirelyPrivate(content)) {
+    return {
+      observationId: null,
+      recorded: false,
+      type: null,
+      importance: 0
+    };
+  }
+  content = stripPrivateTags(content);
   if (shouldExclude(content, config.privacy.exclude_patterns)) {
     return {
       observationId: null,

package/dist/hooks/session-end.js

@@ -1,9 +1,9 @@
 import {
   createMemoryStore
-} from "../chunk-v8anyhk1.js";
+} from "../chunk-gy7xx0jv.js";
 import {
   createDBClient
-} from "../chunk-41rc1bhg.js";
+} from "../chunk-jz140n5a.js";
 import {
   ensureProjectDirs,
   getProjectDBPath
@@ -86,4 +86,3 @@ export {
   sessionEndHook,
   generateSummary
 };
-export { sessionEndHook };

package/dist/hooks/session-start.js

@@ -4,10 +4,10 @@ import {
 import {
   createMemoryStore,
   estimateTokens
-} from "../chunk-v8anyhk1.js";
+} from "../chunk-gy7xx0jv.js";
 import {
   createDBClient
-} from "../chunk-41rc1bhg.js";
+} from "../chunk-jz140n5a.js";
 import {
   ensureProjectDirs,
   getProjectDBPath
@@ -92,4 +92,3 @@ export {
   formatSessionContext,
   backupDatabase
 };
-export { sessionStartHook };

package/dist/hooks/stop.js

@@ -0,0 +1,61 @@
+import {
+  createDBClient
+} from "../chunk-jz140n5a.js";
+import {
+  ensureProjectDirs,
+  getProjectDBPath
+} from "../chunk-w40c0y00.js";
+import"../chunk-ns0dgdnb.js";
+
+// src/hooks/stop.ts
+async function stopHook(context, options) {
+  const {
+    sessionId,
+    projectPath,
+    signal = "SIGINT",
+    activeLoopRunId
+  } = context;
+  let client;
+  if (options?.client) {
+    client = options.client;
+  } else {
+    ensureProjectDirs(projectPath);
+    const dbPath = getProjectDBPath(projectPath);
+    client = createDBClient(dbPath);
+  }
+  try {
+    const session = client.getSession(sessionId);
+    if (!session || session.ended_at) {
+      return {
+        sessionEnded: false,
+        loopStopped: false,
+        summary: "세션이 이미 종료되었거나 존재하지 않습니다."
+      };
+    }
+    let loopStopped = false;
+    if (activeLoopRunId) {
+      client.db.prepare(`
+				UPDATE loop_runs
+				SET status = 'stopped', ended_at = datetime('now')
+				WHERE id = ? AND status = 'running'
+			`).run(activeLoopRunId);
+      loopStopped = true;
+    }
+    const observations = client.listObservations(sessionId, 1000);
+    const summary = `[${signal}] 세션 강제 종료. 작업 ${observations.length}건 기록됨.`;
+    client.endSession(sessionId, summary);
+    return {
+      sessionEnded: true,
+      loopStopped,
+      summary
+    };
+  } finally {
+    if (!options?.client) {
+      client.close();
+    }
+  }
+}
+export {
+  stopHook
+};
+

package/dist/hooks/user-prompt-submit.js

@@ -3,13 +3,13 @@ import {
 } from "../chunk-c3a91ngd.js";
 import {
   estimateTokens
-} from "../chunk-v8anyhk1.js";
+} from "../chunk-gy7xx0jv.js";
 import {
   createSearchEngine
-} from "../chunk-kga64hvg.js";
+} from "../chunk-rcnembz5.js";
 import {
   createDBClient
-} from "../chunk-41rc1bhg.js";
+} from "../chunk-jz140n5a.js";
 import {
   ensureProjectDirs,
   getProjectDBPath
@@ -231,4 +231,3 @@ export {
   extractKeywords
 };
 
-export { userPromptSubmitHook };

package/dist/index.js

@@ -1,3 +1,22 @@
+import"./chunk-c3a91ngd.js";
+import {
+  createMemoryStore,
+  estimateTokens
+} from "./chunk-gy7xx0jv.js";
+import {
+  createSearchEngine
+} from "./chunk-rcnembz5.js";
+import {
+  createDBClient
+} from "./chunk-jz140n5a.js";
+import {
+  ensureProjectDirs,
+  getProjectDBPath
+} from "./chunk-w40c0y00.js";
+import"./chunk-ns0dgdnb.js";
+import {
+  memInjectSkill
+} from "./skills/mem-inject.js";
 import {
   ralphSkill
 } from "./skills/ralph.js";
@@ -7,36 +26,282 @@ import {
 import {
   userPromptSubmitHook
 } from "./hooks/user-prompt-submit.js";
+import {
+  stopHook
+} from "./hooks/stop.js";
 import {
   postToolUseHook
 } from "./hooks/post-tool-use.js";
 import {
   sessionStartHook
 } from "./hooks/session-start.js";
-import"./chunk-c3a91ngd.js";
 import {
   sessionEndHook
 } from "./hooks/session-end.js";
-import {
-  createMemoryStore,
-  estimateTokens
-} from "./chunk-v8anyhk1.js";
 import {
   memForgetSkill
 } from "./skills/mem-forget.js";
-import {
-  memInjectSkill
-} from "./skills/mem-inject.js";
 import {
   memSearchSkill
 } from "./skills/mem-search.js";
-import {
-  createSearchEngine
-} from "./chunk-kga64hvg.js";
-import"./chunk-41rc1bhg.js";
-import"./chunk-w40c0y00.js";
-import"./chunk-ns0dgdnb.js";
+// src/mcp/server.ts
+var MCP_TOOLS = [
+  {
+    name: "ralph_mem_search",
+    description: "Search memories using Progressive Disclosure. Layer 1 returns compact results (~50-100 tokens), Layer 2 adds context (~200-300 tokens), Layer 3 returns full details (~500-1000 tokens).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query"
+        },
+        layer: {
+          type: "number",
+          description: "Detail level (1=index, 2=context, 3=full)",
+          enum: [1, 2, 3],
+          default: 1
+        },
+        limit: {
+          type: "number",
+          description: "Maximum results to return",
+          default: 10
+        },
+        since: {
+          type: "string",
+          description: "Filter results after this date (ISO format or relative like '7d')"
+        },
+        types: {
+          type: "array",
+          items: { type: "string" },
+          description: "Filter by observation types (tool_use, bash, error, success, note)"
+        }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "ralph_mem_timeline",
+    description: "Get time-ordered observations around a specific observation. Useful for understanding context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        observationId: {
+          type: "string",
+          description: "The observation ID to center the timeline around"
+        },
+        before: {
+          type: "number",
+          description: "Number of observations before",
+          default: 3
+        },
+        after: {
+          type: "number",
+          description: "Number of observations after",
+          default: 3
+        }
+      },
+      required: ["observationId"]
+    }
+  },
+  {
+    name: "ralph_mem_get",
+    description: "Get full details of a specific observation by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Observation ID"
+        }
+      },
+      required: ["id"]
+    }
+  }
+];
+function parseRelativeDate(str) {
+  const match = str.match(/^(\d+)([dhm])$/);
+  if (!match)
+    return null;
+  const value = Number.parseInt(match[1], 10);
+  const unit = match[2];
+  const now = new Date;
+  switch (unit) {
+    case "d":
+      return new Date(now.getTime() - value * 24 * 60 * 60 * 1000);
+    case "h":
+      return new Date(now.getTime() - value * 60 * 60 * 1000);
+    case "m":
+      return new Date(now.getTime() - value * 60 * 1000);
+    default:
+      return null;
+  }
+}
+function handleToolCall(call, projectPath) {
+  try {
+    ensureProjectDirs(projectPath);
+    const dbPath = getProjectDBPath(projectPath);
+    switch (call.name) {
+      case "ralph_mem_search":
+        return handleSearch(call.arguments, dbPath);
+      case "ralph_mem_timeline":
+        return handleTimeline(call.arguments, dbPath);
+      case "ralph_mem_get":
+        return handleGet(call.arguments, dbPath);
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${call.name}` }],
+          isError: true
+        };
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+}
+function handleSearch(args, dbPath) {
+  const query = args.query;
+  const layer = args.layer ?? 1;
+  const limit = args.limit ?? 10;
+  const sinceStr = args.since;
+  const types = args.types;
+  const options = { layer, limit, types };
+  if (sinceStr) {
+    const relativeDate = parseRelativeDate(sinceStr);
+    if (relativeDate) {
+      options.since = relativeDate;
+    } else {
+      const isoDate = new Date(sinceStr);
+      if (!Number.isNaN(isoDate.getTime())) {
+        options.since = isoDate;
+      }
+    }
+  }
+  const engine = createSearchEngine(dbPath);
+  try {
+    const results = engine.search(query, options);
+    if (results.length === 0) {
+      return {
+        content: [{ type: "text", text: "No results found." }]
+      };
+    }
+    const formatted = results.map((r, i) => {
+      const parts = [`${i + 1}. [${r.id}] (score: ${r.score.toFixed(2)})`];
+      if (r.summary) {
+        parts.push(`   ${r.summary}`);
+      }
+      if (layer >= 2 && r.createdAt) {
+        parts.push(`   Time: ${r.createdAt.toISOString()}`);
+        if (r.type)
+          parts.push(`   Type: ${r.type}`);
+        if (r.toolName)
+          parts.push(`   Tool: ${r.toolName}`);
+      }
+      if (layer >= 3 && r.content) {
+        parts.push(`   Content: ${r.content}`);
+      }
+      return parts.join(`
+`);
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Found ${results.length} results:
+
+${formatted.join(`
 
+`)}`
+        }
+      ]
+    };
+  } finally {
+    engine.close();
+  }
+}
+function handleTimeline(args, dbPath) {
+  const observationId = args.observationId;
+  const before = args.before ?? 3;
+  const after = args.after ?? 3;
+  const client = createDBClient(dbPath);
+  try {
+    const target = client.getObservation(observationId);
+    if (!target) {
+      return {
+        content: [
+          { type: "text", text: `Observation not found: ${observationId}` }
+        ],
+        isError: true
+      };
+    }
+    const beforeObs = client.db.prepare(`
+				SELECT * FROM observations
+				WHERE session_id = ? AND created_at < ?
+				ORDER BY created_at DESC
+				LIMIT ?
+			`).all(target.session_id, target.created_at, before);
+    const afterObs = client.db.prepare(`
+				SELECT * FROM observations
+				WHERE session_id = ? AND created_at > ?
+				ORDER BY created_at ASC
+				LIMIT ?
+			`).all(target.session_id, target.created_at, after);
+    const formatObs = (o, marker = "") => {
+      const summary = o.content.slice(0, 100) + (o.content.length > 100 ? "..." : "");
+      return `${marker}[${o.id}] ${o.created_at}
+   Type: ${o.type}${o.tool_name ? `, Tool: ${o.tool_name}` : ""}
+   ${summary}`;
+    };
+    const lines = [
+      "=== Timeline ===",
+      "",
+      ...beforeObs.reverse().map((o) => formatObs(o)),
+      "",
+      formatObs(target, ">>> "),
+      "",
+      ...afterObs.map((o) => formatObs(o))
+    ];
+    return {
+      content: [{ type: "text", text: lines.join(`
+`) }]
+    };
+  } finally {
+    client.close();
+  }
+}
+function handleGet(args, dbPath) {
+  const id = args.id;
+  const client = createDBClient(dbPath);
+  try {
+    const obs = client.getObservation(id);
+    if (!obs) {
+      return {
+        content: [{ type: "text", text: `Observation not found: ${id}` }],
+        isError: true
+      };
+    }
+    const details = [
+      `ID: ${obs.id}`,
+      `Session: ${obs.session_id}`,
+      `Type: ${obs.type}`,
+      `Tool: ${obs.tool_name ?? "N/A"}`,
+      `Importance: ${obs.importance}`,
+      `Created: ${obs.created_at}`,
+      "",
+      "Content:",
+      obs.content
+    ];
+    return {
+      content: [{ type: "text", text: details.join(`
+`) }]
+    };
+  } finally {
+    client.close();
+  }
+}
 // src/index.ts
 var VERSION = "0.1.0";
 async function activate() {
@@ -47,6 +312,7 @@ async function deactivate() {
 }
 export {
   userPromptSubmitHook,
+  stopHook,
   sessionStartHook,
   sessionEndHook,
   ralphSkill,
@@ -55,10 +321,12 @@ export {
   memSearchSkill,
   memInjectSkill,
   memForgetSkill,
+  handleToolCall,
   estimateTokens,
   deactivate,
   createSearchEngine,
   createMemoryStore,
   activate,
-  VERSION
+  VERSION,
+  MCP_TOOLS
 };

package/dist/skills/mem-search.js

@@ -1,9 +1,9 @@
 import {
   createSearchEngine
-} from "../chunk-kga64hvg.js";
+} from "../chunk-rcnembz5.js";
 import {
   createDBClient
-} from "../chunk-41rc1bhg.js";
+} from "../chunk-jz140n5a.js";
 import {
   ensureProjectDirs,
   getProjectDBPath

package/dist/skills/mem-status.js

@@ -197,4 +197,3 @@ export {
   createMemStatusSkill
 };
 
-export { memStatusSkill };

package/dist/skills/ralph.js

@@ -3,7 +3,7 @@ import {
 } from "../chunk-c3a91ngd.js";
 import {
   createDBClient
-} from "../chunk-41rc1bhg.js";
+} from "../chunk-jz140n5a.js";
 import {
   ensureProjectDirs,
   getProjectDBPath,
@@ -651,4 +651,3 @@ export {
   createRalphSkill
 };
 
-export { ralphSkill };

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node $CLAUDE_PLUGIN_ROOT/dist/hooks/post-tool-use.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node $CLAUDE_PLUGIN_ROOT/dist/hooks/stop.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "ralph-mem",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "module",
   "description": "Persistent context management plugin for Claude Code with Ralph Loop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "plugin.json",
+    ".claude-plugin",
+    "commands",
+    "skills",
+    "hooks",
     "prompts"
   ],
   "repository": {

package/skills/mem-forget/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: mem-forget
+description: 특정 메모리 항목을 삭제합니다. 더 이상 필요 없는 컨텍스트를 정리할 때 사용합니다.
+---
+
+# Memory Forget
+
+특정 메모리 항목을 삭제합니다.
+
+## 사용법
+
+```
+/mem-forget obs-a1b2c3d4
+/mem-forget --session sess-xyz123
+/mem-forget --before 30d
+```
+
+## 옵션
+
+- `--session <id>` - 특정 세션의 모든 관찰 삭제
+- `--before <duration>` - 지정 기간 이전의 관찰 삭제
+- `--type <type>` - 특정 타입의 관찰만 삭제
+- `--dry-run` - 실제 삭제 없이 대상 확인
+
+$ARGUMENTS

package/skills/mem-inject/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: mem-inject
+description: 수동으로 컨텍스트를 메모리에 주입합니다. 중요한 정보를 영구 저장할 때 사용합니다.
+---
+
+# Memory Inject
+
+수동으로 컨텍스트를 메모리에 저장합니다.
+
+## 사용법
+
+```
+/mem-inject "이 프로젝트는 Express + Prisma 기반"
+/mem-inject "API 엔드포인트는 /api/v1 prefix 사용" --type note
+```
+
+## 옵션
+
+- `--type <type>` - 관찰 타입 (note, tool_use, bash, error, success)
+- `--tags <tags>` - 태그 (쉼표로 구분)
+
+$ARGUMENTS

package/skills/mem-search/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: mem-search
+description: 저장된 메모리를 검색합니다. Progressive disclosure로 토큰을 효율적으로 사용합니다.
+---
+
+# Memory Search
+
+저장된 관찰 기록과 세션 정보를 검색합니다.
+
+## 사용법
+
+```
+/mem-search "authentication error"
+/mem-search "JWT" --since 7d
+/mem-search --layer 3 obs-a1b2c3d4
+```
+
+## 옵션
+
+- `--layer <1|2|3>` - 검색 레이어 지정
+  - Layer 1: Index (ID + 점수) - 50-100 토큰/결과
+  - Layer 2: Timeline (시간순 컨텍스트) - 200-300 토큰/결과
+  - Layer 3: Full Details - 500-1000 토큰/결과
+- `--since <duration>` - 시간 범위 (예: 7d, 24h)
+- `--limit <n>` - 최대 결과 수
+
+$ARGUMENTS

package/skills/mem-status/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: mem-status
+description: 메모리 상태와 통계를 확인합니다. 저장된 세션 수, 관찰 수, 스토리지 사용량 등을 표시합니다.
+---
+
+# Memory Status
+
+메모리 시스템의 현재 상태를 확인합니다.
+
+## 사용법
+
+```
+/mem-status
+/mem-status --detailed
+```
+
+## 출력 정보
+
+- 총 세션 수
+- 총 관찰 수
+- 타입별 관찰 분포
+- 스토리지 사용량
+- 최근 활동
+
+## 옵션
+
+- `--detailed` - 상세 통계 표시
+- `--json` - JSON 형식으로 출력
+
+$ARGUMENTS

package/skills/ralph/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ralph
+description: Ralph Loop 제어 - 성공할 때까지 반복 실행합니다. start, stop, status, config 서브커맨드를 지원합니다.
+---
+
+# Ralph Loop
+
+성공 기준을 달성할 때까지 작업을 자동으로 반복 실행합니다.
+
+## 사용법
+
+### 시작
+```
+/ralph start "Implement feature X"
+/ralph start "Fix lint errors" --criteria lint_clean
+```
+
+### 상태 확인
+```
+/ralph status
+```
+
+### 중단
+```
+/ralph stop
+/ralph stop --rollback  # 변경사항 롤백
+```
+
+### 설정
+```
+/ralph config
+/ralph config --max-iterations 15
+```
+
+## 성공 기준
+
+- `test_pass` - 테스트 통과 (기본값)
+- `build_success` - 빌드 성공
+- `lint_clean` - Lint 오류 없음
+- `type_check` - 타입 체크 통과
+- `custom` - 사용자 정의 명령
+
+$ARGUMENTS

package/plugin.json

@@ -1,51 +0,0 @@
-{
-  "name": "ralph-mem",
-  "version": "0.1.0",
-  "description": "Persistent context management with Ralph Loop",
-  "main": "dist/index.js",
-  "hooks": [
-    {
-      "event": "SessionStart",
-      "handler": "dist/hooks/session-start.js"
-    },
-    {
-      "event": "SessionEnd",
-      "handler": "dist/hooks/session-end.js"
-    },
-    {
-      "event": "UserPromptSubmit",
-      "handler": "dist/hooks/user-prompt-submit.js"
-    },
-    {
-      "event": "PostToolUse",
-      "handler": "dist/hooks/post-tool-use.js"
-    }
-  ],
-  "skills": [
-    {
-      "name": "ralph",
-      "description": "Ralph Loop control - start, stop, status",
-      "handler": "dist/skills/ralph.js"
-    },
-    {
-      "name": "mem-search",
-      "description": "Search memory with progressive disclosure",
-      "handler": "dist/skills/mem-search.js"
-    },
-    {
-      "name": "mem-inject",
-      "description": "Manually inject context into memory",
-      "handler": "dist/skills/mem-inject.js"
-    },
-    {
-      "name": "mem-forget",
-      "description": "Remove specific memory entries",
-      "handler": "dist/skills/mem-forget.js"
-    },
-    {
-      "name": "mem-status",
-      "description": "View memory status and statistics",
-      "handler": "dist/skills/mem-status.js"
-    }
-  ]
-}