@hir4ta/mneme 0.17.0

package/README.md

@@ -0,0 +1,410 @@
+# mneme
+
+> **⚠️ Breaking Change (v0.17.0)**: Renamed from `memoria` to `mneme`.
+> If upgrading from `@hir4ta/memoria`, please reinstall:
+> ```bash
+> claude mcp remove mneme-search mneme-db
+> claude plugin remove @hir4ta/memoria
+> claude plugin add @hir4ta/mneme
+> ```
+> Data directory changed: `.memoria/` → `.mneme/`
+> Rename manually: `mv .memoria .mneme`
+
+Long-term memory plugin for Claude Code
+
+Provides automatic session saving, intelligent memory search, and web dashboard management.
+
+## Features
+
+### Core Features
+- **Auto-save interactions**: Conversations auto-saved at session end (jq-based, reliable)
+- **Auto memory search**: Related past sessions/decisions automatically injected on each prompt
+- **Backup on PreCompact**: Interactions backed up before Auto-Compact (context 95% full)
+- **Full data extraction**: Save summary, decisions, patterns, and rules with `/mneme:save`
+- **Memory-informed planning**: Design and plan with past knowledge via `/mneme:plan`
+- **Session Resume**: Resume past sessions with `/mneme:resume` (with chain tracking)
+- **Session Suggestion**: Recent 3 sessions shown at session start
+- **Rule-based Review**: Code review based on `dev-rules.json` / `review-guidelines.json`
+- **GitHub PR Review**: Review GitHub PRs with `/mneme:review <PR URL>`
+- **Knowledge Harvesting**: Extract rules and patterns from PR comments with `/mneme:harvest`
+- **Weekly Reports**: Auto-generate Markdown reports aggregating review results
+- **Web Dashboard**: View sessions, decisions, patterns, and rules
+
+## Problems Solved
+
+### Common Issues in Claude Code Development
+
+- **Context Loss**: Conversation context is lost on session end or Auto-Compact
+- **Opaque Decisions**: "Why did we choose this design?" becomes untraceable
+- **Repeated Mistakes**: Same errors solved multiple times without learning
+- **Hard to Reuse Knowledge**: Past interactions and decisions are hard to search
+
+### What mneme Enables
+
+- **Auto-save + Resume** enables context continuity across sessions
+- **Auto memory search** brings relevant past knowledge to every conversation
+- **Decision & Pattern Recording** tracks reasoning and error solutions
+- **Search and Dashboard** for quick access to past records
+- **Review Feature** for repository-specific code review
+
+### Team Benefits
+
+- `.mneme/` JSON files are **Git-manageable**, enabling team sharing of decisions and session history
+- Quickly understand background and context during onboarding or reviews
+
+## Installation
+
+### Prerequisites
+
+- **jq**: Used for JSON processing in hooks
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# Windows (Chocolatey)
+choco install jq
+
+# Windows (Scoop)
+scoop install jq
+
+# Windows (winget)
+winget install jqlang.jq
+```
+
+### Plugin Installation
+
+Run the following in Claude Code:
+
+```bash
+/plugin marketplace add hir4ta/mneme-marketplace
+/plugin install mneme@mneme-marketplace
+```
+
+Then initialize mneme in your project:
+
+```bash
+# In Claude Code
+/init-mneme
+
+# Or from terminal
+npx @hir4ta/mneme --init
+```
+
+Restart Claude Code to complete installation.
+
+## Update
+
+Run the following in Claude Code:
+
+```bash
+/plugin marketplace update mneme-marketplace
+```
+
+Restart Claude Code.
+
+### Enable Auto-Update (Recommended)
+
+1. Run `/plugin`
+2. Select Marketplaces tab
+3. Select `mneme-marketplace`
+4. Enable "Enable auto-update"
+
+This will auto-update on Claude Code startup.
+
+## Usage
+
+### Session Auto-Save
+
+**Interactions are auto-saved** at session end using jq (no Claude dependency). No configuration needed.
+
+**PreCompact** backs up interactions to `preCompactBackups` before Auto-Compact (context 95% full). Summary is NOT auto-created.
+
+### Auto Memory Search
+
+**On every prompt**, mneme automatically:
+1. Extracts keywords from your message
+2. Searches sessions/decisions/patterns
+3. Injects relevant context to Claude
+
+This means past knowledge is always available without manual lookup.
+
+### Session Suggestion
+
+At session start, recent 3 sessions are shown:
+
+```
+**Recent sessions:**
+  1. [abc123] JWT authentication implementation (2026-01-27, main)
+  2. [def456] Dashboard UI improvements (2026-01-26, main)
+  3. [ghi789] Bug fixes (2026-01-25, main)
+
+Continue from a previous session? Use `/mneme:resume <id>`
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/init-mneme` | Initialize mneme in current project |
+| `/mneme:save` | Extract all data: summary, decisions, patterns, rules |
+| `/mneme:plan [topic]` | Memory-informed design + Socratic questions + task breakdown |
+| `/mneme:resume [id]` | Resume session (show list if ID omitted) |
+| `/mneme:search "query"` | Search sessions, decisions, and patterns |
+| `/mneme:review [--staged\|--all\|--diff=branch\|--full]` | Rule-based code review |
+| `/mneme:review <PR URL>` | Review GitHub PR |
+| `/mneme:harvest <PR URL>` | Extract knowledge from PR review comments |
+| `/mneme:report [--from YYYY-MM-DD --to YYYY-MM-DD]` | Weekly review report |
+
+### Recommended Workflow
+
+```
+plan → implement → save → review
+```
+
+1. **plan**: Design with memory lookup + Socratic questions + task breakdown
+2. **implement**: Follow the plan
+3. **save**: Extract decisions, patterns, rules
+4. **review**: Verify against plan and code quality
+
+### Dashboard
+
+Run in your project directory:
+
+```bash
+npx @hir4ta/mneme --dashboard
+```
+
+Open <http://localhost:7777> in your browser.
+
+Change port:
+
+```bash
+npx @hir4ta/mneme --dashboard --port 8080
+```
+
+#### Screens
+
+- **Sessions**: List and view sessions
+- **Decisions**: List and view technical decisions
+- **Rules**: View dev rules and review guidelines
+- **Patterns**: View learned patterns (good patterns, anti-patterns, error solutions)
+- **Statistics**: View activity charts and session statistics
+- **Graph**: Visualize session connections by shared tags
+
+#### Language Switching
+
+The dashboard supports English and Japanese. Click the language toggle (EN/JA) in the header to switch. The preference is saved to localStorage.
+
+### MCP Tools
+
+mneme provides MCP servers with search and database tools callable directly from Claude Code:
+
+| Server | Tool | Description |
+|--------|------|-------------|
+| mneme-search | `mneme_search` | Unified search (FTS5, tag alias resolution) |
+| mneme-search | `mneme_get_session` | Get session details |
+| mneme-search | `mneme_get_decision` | Get decision details |
+| mneme-db | `mneme_list_projects` | List all projects |
+| mneme-db | `mneme_cross_project_search` | Cross-project search |
+
+### Subagents
+
+| Agent | Description |
+|-------|-------------|
+| `mneme-reviewer` | Rule-based code review (isolated context) |
+
+## How It Works
+
+```mermaid
+flowchart TB
+    subgraph autosave [Auto-Save Interactions]
+        A[Session End] --> B[SessionEnd Hook]
+        B --> C[jq extracts from transcript]
+        C --> D[interactions + files + metrics]
+    end
+
+    subgraph autosearch [Auto Memory Search]
+        E[User Prompt] --> F[UserPromptSubmit Hook]
+        F --> G[Search sessions/decisions/patterns]
+        G --> H[Inject relevant context]
+    end
+
+    subgraph backup [PreCompact Backup]
+        I[Context 95% Full] --> J[PreCompact Hook]
+        J --> K[Backup interactions to preCompactBackups]
+    end
+
+    subgraph manual [Manual Actions]
+        L["mneme:save"] --> M[Extract decisions + patterns + rules]
+        N["mneme:plan"] --> O[Memory-informed design + tasks]
+    end
+
+    subgraph resume [Session Resume]
+        P["mneme:resume"] --> Q[Select from list]
+        Q --> R[Restore past context + set resumedFrom]
+    end
+
+    subgraph review [Review]
+        S["mneme:review"] --> T[Rule-based findings]
+        T --> U[Save review results]
+    end
+
+    subgraph dashboard [Dashboard]
+        V["npx @hir4ta/mneme -d"] --> W[Open in browser]
+        W --> X[View all data]
+    end
+
+    D --> P
+    H --> L
+    M --> V
+    U --> V
+```
+
+## Data Storage
+
+mneme uses a **hybrid storage** approach for privacy and collaboration:
+
+| Storage | Location | Purpose | Sharing |
+|---------|----------|---------|---------|
+| **JSON** | `.mneme/` | Summaries, decisions, patterns, rules | Git-managed (team shared) |
+| **SQLite** | `.mneme/local.db` | Interactions, backups | Local only (gitignored) |
+
+**Why hybrid?**
+- **Privacy**: Conversation history (interactions) stays local (gitignored)
+- **Lightweight**: JSON files reduced from 100KB+ to ~5KB (interactions excluded)
+- **Future-ready**: Embeddings table prepared for semantic search
+
+### Directory Structure
+
+**Project-local (`.mneme/`)**:
+```text
+.mneme/
+├── local.db          # SQLite with interactions (gitignored)
+├── tags.json         # Tag master file (93 tags, prevents notation variations)
+├── sessions/         # Session metadata (YYYY/MM) - Git-managed
+│   └── YYYY/MM/
+│       └── {id}.json # Metadata only (interactions in local.db)
+├── decisions/        # Technical decisions (from /save) - Git-managed
+│   └── YYYY/MM/
+│       └── {id}.json
+├── patterns/         # Error patterns (from /save) - Git-managed
+│   └── {user}.json
+├── rules/            # Dev rules / review guidelines - Git-managed
+├── reviews/          # Review results (YYYY/MM) - Git-managed
+└── reports/          # Weekly reports (YYYY-MM) - Git-managed
+```
+
+The `local.db` file is automatically added to `.mneme/.gitignore` to keep conversations private.
+
+### Session JSON Schema
+
+Session metadata is stored in JSON (interactions are stored in SQLite for privacy):
+
+```json
+{
+  "id": "abc12345",
+  "sessionId": "full-uuid-from-claude-code",
+  "createdAt": "2026-01-27T10:00:00Z",
+  "endedAt": "2026-01-27T12:00:00Z",
+  "title": "JWT authentication implementation",
+  "tags": ["auth", "jwt"],
+  "context": {
+    "branch": "feature/auth",
+    "projectDir": "/path/to/project",
+    "user": { "name": "tanaka", "email": "tanaka@example.com" }
+  },
+  "metrics": {
+    "userMessages": 5,
+    "assistantResponses": 5,
+    "thinkingBlocks": 5,
+    "toolUsage": [{"name": "Edit", "count": 3}, {"name": "Write", "count": 2}]
+  },
+  "files": [
+    { "path": "src/auth/jwt.ts", "action": "create" }
+  ],
+  "resumedFrom": "def45678",
+  "status": "complete",
+
+  "summary": {
+    "title": "JWT authentication implementation",
+    "goal": "Implement JWT-based auth with refresh token support",
+    "outcome": "success",
+    "description": "Implemented JWT auth with RS256 signing",
+    "sessionType": "implementation"
+  },
+
+  "plan": {
+    "tasks": ["[x] JWT signing method selection", "[x] Middleware implementation", "[ ] Add tests"],
+    "remaining": ["Add tests"]
+  },
+
+  "discussions": [
+    {
+      "topic": "Signing algorithm",
+      "decision": "Adopt RS256",
+      "reasoning": "Security considerations for production",
+      "alternatives": ["HS256 (simpler but requires shared secret)"]
+    }
+  ],
+
+  "errors": [
+    {
+      "error": "secretOrPrivateKey must be asymmetric",
+      "cause": "Using HS256 secret with RS256",
+      "solution": "Generate RS256 key pair"
+    }
+  ],
+
+  "handoff": {
+    "stoppedReason": "Test creation postponed to next session",
+    "notes": ["vitest configured", "Mock key pair in test/fixtures/"],
+    "nextSteps": ["Create jwt.test.ts", "Add E2E tests"]
+  },
+
+  "references": [
+    { "url": "https://jwt.io/introduction", "title": "JWT Introduction" }
+  ]
+}
+```
+
+### Session Types
+
+The `sessionType` field classifies the session type.
+
+| Type | Description |
+|------|-------------|
+| `decision` | Decision cycle present (design choices, tech selection) |
+| `implementation` | Code changes made |
+| `research` | Research, learning, catchup |
+| `exploration` | Codebase exploration |
+| `discussion` | Discussion, consultation only |
+| `debug` | Debugging, investigation |
+| `review` | Code review |
+
+### Tags
+
+Tags are selected from `.mneme/tags.json` to prevent notation variations (e.g., "フロント" → "frontend"). The master file contains 93 tags across 11 categories:
+
+- **domain**: frontend, backend, api, db, infra, mobile, cli
+- **phase**: feature, bugfix, refactor, test, docs
+- **ai**: llm, ai-agent, mcp, rag, vector-db, embedding
+- **cloud**: serverless, microservices, edge, wasm
+- And more...
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+**⚠️ While in 0.x (pre-1.0), breaking changes may occur between minor versions.**
+
+If you encounter issues after an update:
+1. Check the [releases](https://github.com/hir4ta/mneme/releases) for migration notes
+2. Re-initialize with `npx @hir4ta/mneme --init` if needed
+
+## License
+
+MIT

package/bin/mneme.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+import { fork } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Suppress Node.js SQLite experimental warning (must be before dynamic import)
+const originalEmit = process.emit;
+process.emit = (name, data, ...args) => {
+  if (
+    name === "warning" &&
+    data?.name === "ExperimentalWarning" &&
+    data?.message?.includes("SQLite")
+  ) {
+    return false;
+  }
+  return originalEmit.call(process, name, data, ...args);
+};
+
+// Dynamic import to ensure warning suppression is active
+const { DatabaseSync } = await import("node:sqlite");
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+const packageDir = path.dirname(__dirname);
+const projectRoot = process.cwd();
+
+function showHelp() {
+  console.log(`
+mneme - Claude Code Long-term Memory Plugin
+
+Usage:
+  mneme --init         Initialize .mneme directory in current project
+  mneme --dashboard    Start the web dashboard
+  mneme -d             Same as above (short form)
+  mneme --port <port>  Specify port (default: 7777)
+  mneme --help         Show this help
+
+Examples:
+  cd /path/to/your/project
+  npx @hir4ta/mneme --init
+  npx @hir4ta/mneme --dashboard
+  npx @hir4ta/mneme -d --port 8080
+`);
+}
+
+function checkMnemeDir() {
+  const mnemeDir = path.join(projectRoot, ".mneme");
+  if (!fs.existsSync(mnemeDir)) {
+    console.log(`\nWARNING: .mneme directory not found: ${projectRoot}`);
+    console.log("         Run: npx @hir4ta/mneme --init");
+  }
+}
+
+function initMneme() {
+  const mnemeDir = path.join(projectRoot, ".mneme");
+  const sessionsDir = path.join(mnemeDir, "sessions");
+  const rulesDir = path.join(mnemeDir, "rules");
+  const patternsDir = path.join(mnemeDir, "patterns");
+  const tagsPath = path.join(mnemeDir, "tags.json");
+  const localDbPath = path.join(mnemeDir, "local.db");
+  const gitignorePath = path.join(mnemeDir, ".gitignore");
+
+  // Check if already initialized
+  if (fs.existsSync(mnemeDir)) {
+    console.log(`mneme is already initialized: ${mnemeDir}`);
+    return;
+  }
+
+  // Create directories
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  fs.mkdirSync(rulesDir, { recursive: true });
+  fs.mkdirSync(patternsDir, { recursive: true });
+
+  // Copy default tags.json
+  const defaultTagsPath = path.join(packageDir, "hooks", "default-tags.json");
+  if (fs.existsSync(defaultTagsPath)) {
+    fs.copyFileSync(defaultTagsPath, tagsPath);
+  }
+
+  // Initialize rules files
+  const now = new Date().toISOString();
+  const rulesTemplate = JSON.stringify(
+    {
+      schemaVersion: 1,
+      createdAt: now,
+      updatedAt: now,
+      items: [],
+    },
+    null,
+    2,
+  );
+
+  fs.writeFileSync(
+    path.join(rulesDir, "review-guidelines.json"),
+    rulesTemplate,
+  );
+  fs.writeFileSync(path.join(rulesDir, "dev-rules.json"), rulesTemplate);
+
+  // Create .gitignore for local.db
+  const gitignoreContent = `# Local SQLite database (private interactions)
+local.db
+local.db-wal
+local.db-shm
+`;
+  fs.writeFileSync(gitignorePath, gitignoreContent);
+
+  // Initialize local SQLite database
+  const schemaPath = path.join(packageDir, "lib", "schema.sql");
+  try {
+    const db = new DatabaseSync(localDbPath);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA synchronous = NORMAL");
+    if (fs.existsSync(schemaPath)) {
+      const schema = fs.readFileSync(schemaPath, "utf-8");
+      db.exec(schema);
+    }
+    db.close();
+  } catch (error) {
+    console.error(
+      `Warning: Failed to initialize SQLite database: ${error.message}`,
+    );
+  }
+
+  console.log(`mneme initialized: ${mnemeDir}`);
+  console.log(`
+Created:
+  ${sessionsDir}/
+  ${rulesDir}/
+  ${patternsDir}/
+  ${tagsPath}
+  ${rulesDir}/review-guidelines.json
+  ${rulesDir}/dev-rules.json
+  ${gitignorePath}
+  ${localDbPath}
+
+You can now use mneme with Claude Code in this project.
+`);
+}
+
+function getPort() {
+  const portIndex = args.indexOf("--port");
+  if (portIndex !== -1 && args[portIndex + 1]) {
+    return parseInt(args[portIndex + 1], 10) || 7777;
+  }
+  return 7777;
+}
+
+function startDashboard() {
+  checkMnemeDir();
+
+  const port = getPort();
+  const serverPath = path.join(packageDir, "dist", "server.js");
+
+  if (!fs.existsSync(serverPath)) {
+    console.error("ERROR: Server build not found.");
+    console.error("       The package may not be installed correctly.");
+    process.exit(1);
+  }
+
+  const child = fork(serverPath, [], {
+    cwd: packageDir,
+    env: {
+      ...process.env,
+      MNEME_PROJECT_ROOT: projectRoot,
+      PORT: port.toString(),
+    },
+    stdio: "inherit",
+  });
+
+  child.on("error", (err) => {
+    console.error("ERROR: Failed to start dashboard:", err.message);
+    process.exit(1);
+  });
+
+  child.on("close", (code) => {
+    process.exit(code || 0);
+  });
+
+  process.on("SIGINT", () => {
+    child.kill("SIGINT");
+  });
+}
+
+// Parse arguments
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  showHelp();
+  process.exit(0);
+}
+
+if (args.includes("--init")) {
+  initMneme();
+} else if (args.includes("--dashboard") || args.includes("-d")) {
+  startDashboard();
+} else {
+  console.error(`ERROR: Unknown option: ${args.join(" ")}`);
+  showHelp();
+  process.exit(1);
+}