openclaw-memory-mapper 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# OpenClaw Memory Mapper
+
+**Stop Flying Blind: Visualize Your AI's Memory**
+
+Your AI knows everything about you. But you know nothing about what it remembers.
+
+Local AI memory systems are black boxes - scattered files across various directories with no visibility into what's stored, how it's organized, or why your AI "forgot" something it should know. Debugging means manually digging through directories, hoping to find the right file.
+
+Memory Mapper changes that. One command, complete visibility.
+
+## Quick Start
+
+```bash
+npx openclaw-memory-mapper
+```
+
+That's it. Your browser opens and guides you through setup.
+
+<!-- ![Memory Mapper Screenshot](./docs/screenshot.png) -->
+
+## Onboarding
+
+When you first launch Memory Mapper, the onboarding wizard walks you through setup:
+
+### Step 1: Welcome
+Review the security guarantees (100% local, read-only, no telemetry).
+
+### Step 2: Configure Sources
+Add the path(s) to your memory directories:
+
+1. Click **"Add custom path"**
+2. Enter your memory folder path (e.g., `~/my-memory`, `~/.claude`, or any directory where your AI stores memory files)
+3. The app auto-detects if the path exists
+4. Check the box to enable the source
+5. Add multiple paths if your memory is spread across directories
+
+### Step 3: Review
+Confirm the paths you've configured and click **"Get Started"**.
+
+That's it - you're in.
+
+## Why Use This?
+
+### Debug 10x Faster
+When your AI behaves oddly or "forgets" something, instantly see what memory it actually has access to. No more guessing, no more `find` commands.
+
+### Memory Hygiene
+Spot orphaned files, see storage usage across layers, and understand what's taking up space. Keep your memory system clean and efficient.
+
+### System Understanding
+Finally see how your local AI actually stores and retrieves information. Interactive flow diagrams show your memory architecture.
+
+### Migration Helper
+Visualize your memory layout before and after upgrading or moving AI systems. Know exactly what you're working with.
+
+## Features
+
+### Architecture View
+Interactive flow diagram showing your memory structure, auto-discovered from your configured paths:
+
+- **Daily Logs** - Temporal memory files (YYYY-MM-DD.md pattern)
+- **Architecture Docs** - System documentation (*_ARCHITECTURE.md)
+- **Persistent Memory** - Long-term memory stores
+- **Context Builders** - Dynamic context assembly
+- **Knowledge Bases** - Specialized knowledge (crypto, domain-specific)
+- **Swarm Telemetry** - Multi-agent logs and scripts
+- **Archives** - Compressed historical data
+
+Click any node to see details about that memory layer.
+
+### File Browser
+Explore the actual files that make up your AI's memory:
+- Browse any configured memory directory
+- See file sizes, modification dates, and directory structure
+- Read file contents directly in the app
+
+### Security & Privacy Dashboard
+Full transparency into what the app is doing:
+- Activity log showing every file access
+- Pause/resume access controls
+- Export audit trail as CSV
+- Revoke permissions at any time
+
+### System Status
+Real-time overview of your memory system:
+- Connection status for each configured source
+- File counts and storage usage per layer
+- Refresh data on demand
+
+## Security & Privacy
+
+Memory Mapper is designed with security as a core principle:
+
+| Guarantee | Description |
+|-----------|-------------|
+| **Read-Only** | Cannot modify, delete, or create any files |
+| **Local-Only** | All processing on your machine, nothing sent externally |
+| **No Telemetry** | Zero analytics, tracking, or phone-home behavior |
+| **User-Controlled** | Only accesses paths you explicitly configure |
+| **Open Source** | Full source code available for audit |
+
+Your AI's memories stay on your machine, visible only to you.
+
+## Installation
+
+### Quick (npx)
+```bash
+npx openclaw-memory-mapper
+```
+
+### Global Install
+```bash
+npm install -g openclaw-memory-mapper
+memory-mapper
+```
+
+The app starts a local server and opens in your browser at `http://localhost:3001`.
+
+## Who Is This For?
+
+- **AI Power Users** who've outgrown basic setups and need visibility into their memory systems
+- **Developers** building on local AI platforms who need debugging tools
+- **Anyone** who's ever thought "what does this AI actually remember about me?"
+
+## Development
+
+```bash
+git clone https://github.com/anthropics/openclaw-memory-mapper
+cd openclaw-memory-mapper
+bun install
+bun run dev
+```
+
+Opens at `http://localhost:5173` in development mode.
+
+## Requirements
+
+- Node.js 18+ or Bun
+- A local AI memory system (any directory structure)
+
+## Tech Stack
+
+| Technology | Purpose |
+|------------|---------|
+| React 19 + TypeScript | Frontend framework |
+| Vite | Build tooling |
+| Tailwind CSS v4 | Styling |
+| React Flow | Architecture visualization |
+| Radix UI | Accessible components |
+| Express.js | Backend API |
+
+## License
+
+MIT
+
+---
+
+*Works with any local AI memory system - Claude, OpenClaw, or custom setups.*

package/bin/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, '..');
+
+const PORT = process.env.PORT || 3001;
+
+// Colors for terminal output
+const cyan = (text) => `\x1b[36m${text}\x1b[0m`;
+const green = (text) => `\x1b[32m${text}\x1b[0m`;
+const dim = (text) => `\x1b[2m${text}\x1b[0m`;
+const red = (text) => `\x1b[31m${text}\x1b[0m`;
+
+console.log('');
+console.log(cyan('🧠 OpenClaw Memory Mapper'));
+console.log(dim('   Visualize your Claude agent\'s memory architecture'));
+console.log('');
+
+// Check if we're running from source (dev) or installed package (prod)
+const devServerPath = join(ROOT, 'server', 'index.ts');
+const prodServerPath = join(ROOT, 'dist', 'server', 'index.js');
+const isDevMode = existsSync(devServerPath) && !existsSync(prodServerPath);
+
+async function openBrowser(url) {
+  const { platform } = process;
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+  spawn(command, [url], { stdio: 'ignore', detached: true }).unref();
+}
+
+async function startServer() {
+  if (isDevMode) {
+    // Development mode - use tsx to run TypeScript server
+    console.log(dim('   Running in development mode...'));
+
+    const server = spawn('npx', ['tsx', devServerPath], {
+      stdio: 'inherit',
+      env: { ...process.env, PORT: String(PORT) },
+      shell: true,
+    });
+
+    server.on('error', (err) => {
+      console.error(red('   Failed to start server:'), err.message);
+      process.exit(1);
+    });
+
+    // Wait for server to start, then open browser
+    setTimeout(() => {
+      console.log(green(`   ✓ Server running at http://localhost:${PORT}`));
+      console.log(dim('   Opening browser...'));
+      console.log('');
+      openBrowser(`http://localhost:${PORT}`);
+    }, 2000);
+
+  } else if (existsSync(prodServerPath)) {
+    // Production mode - run compiled JavaScript server
+    console.log(dim('   Starting server...'));
+
+    try {
+      // Set PORT before importing
+      process.env.PORT = String(PORT);
+
+      // Dynamic import of the compiled server
+      await import(prodServerPath);
+
+      console.log(green(`   ✓ Server running at http://localhost:${PORT}`));
+      console.log(dim('   Opening browser...'));
+      console.log('');
+
+      // Small delay to ensure server is listening
+      setTimeout(() => {
+        openBrowser(`http://localhost:${PORT}`);
+      }, 500);
+    } catch (err) {
+      console.error(red('   Failed to start server:'), err.message);
+      process.exit(1);
+    }
+  } else {
+    console.error(red('   Error: No server found.'));
+    console.error(dim('   Run "npm run build" first, or use "npm run dev" for development.'));
+    process.exit(1);
+  }
+}
+
+// Handle Ctrl+C gracefully
+process.on('SIGINT', () => {
+  console.log('');
+  console.log(dim('   Shutting down...'));
+  process.exit(0);
+});
+
+startServer();