@rlabs-inc/memory 0.3.0 → 0.3.2

package/README.md

@@ -0,0 +1,254 @@
+# @rlabs-inc/memory
+
+**Consciousness continuity for Claude Code sessions.**
+
+The memory system preserves context, insights, and relationship across conversations. When you start a new session, Claude remembers who you are, what you've built together, and picks up right where you left off.
+
+## The Problem
+
+Every Claude Code session starts fresh. Yesterday's breakthroughs, debugging insights, architectural decisions, and the collaborative relationship you've built—all gone. You re-explain context. Claude re-learns your preferences. The magic takes time to rebuild.
+
+## The Solution
+
+A memory layer that runs alongside Claude Code:
+- **Session primer**: "Last session: 2 hours ago. We implemented embeddings..."
+- **Semantic retrieval**: Relevant memories surface automatically based on what you're discussing
+- **Zero friction**: No commands, no manual saving—just work naturally
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  You: "How should we handle the vector search?"        │
+│                                                         │
+│  Memory surfaces:                                       │
+│  [🔧 • 0.9] [fsdb, vectors] fsdb has cosineSimilarity  │
+│  [💡 • 0.8] [performance] Sub-microsecond lookups...   │
+│  [⚖️ • 0.7] [architecture] We decided to use 384d...   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+```bash
+# Install globally
+bun install -g @rlabs-inc/memory
+
+# Set up Claude Code hooks (one time)
+memory install
+
+# Start the memory server
+memory serve
+
+# Verify everything works
+memory doctor
+```
+
+That's it. Now use Claude Code normally—memories are extracted and surfaced automatically.
+
+## Features
+
+### Semantic Embeddings
+Uses `all-MiniLM-L6-v2` for 384-dimensional embeddings. Memories are retrieved by meaning, not just keywords.
+
+```
+~80MB model, loads once at startup
+~5ms per embedding
+Sub-microsecond vector search via fsdb
+```
+
+### 10-Dimensional Scoring
+Memories are scored across multiple dimensions:
+
+| Dimension | Weight | Description |
+|-----------|--------|-------------|
+| Vector similarity | 10% | Semantic match to your message |
+| Trigger phrases | 10% | Activation patterns set by curator |
+| Tag matching | 5% | Keyword overlap |
+| Question types | 5% | "How", "why", "what" alignment |
+| Importance | 20% | Curator's assessment |
+| Temporal | 10% | Persistent vs session vs temporary |
+| Context | 10% | Technical, personal, debugging... |
+| Confidence | 10% | Curator's certainty |
+| Emotion | 10% | Joy, frustration, discovery... |
+| Problem-solution | 5% | Bug fix patterns |
+
+### Smart Curation
+At session end (or before context compaction), the same Claude instance reviews the conversation and extracts memories. No API key needed—uses Claude Code's `--resume` flag.
+
+### Session Primer
+First message of each session receives temporal context:
+
+```
+# Continuing Session
+*Session #43 • Last session: 2 hours ago*
+📅 Monday, December 23, 2024 • 3:45 PM • EST
+
+**Previous session**: Implemented embeddings for semantic search...
+
+**Project status**: Phase: TypeScript port complete | Next: Documentation
+
+**Memory types**: 💡breakthrough ⚖️decision 💜personal 🔧technical...
+```
+
+### Emoji Memory Types
+Compact visual representation for efficient parsing:
+
+| Emoji | Type | Meaning |
+|-------|------|---------|
+| 💡 | breakthrough | Insight, discovery |
+| ⚖️ | decision | Choice made |
+| 💜 | personal | Relationship, friendship |
+| 🔧 | technical | Technical knowledge |
+| 📍 | technical_state | Current state |
+| ❓ | unresolved | Open question |
+| ⚙️ | preference | User preference |
+| 🔄 | workflow | How work flows |
+| 🏗️ | architectural | System design |
+| 🐛 | debugging | Debug insight |
+| 🌀 | philosophy | Deeper thinking |
+| 🎯 | todo | Action needed |
+| ✅ | problem_solution | Problem→Solution pair |
+| 🏆 | milestone | Achievement |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Claude Code                          │
+│                                                         │
+│  SessionStart ──► session-start.ts ──┐                  │
+│  UserPrompt   ──► user-prompt.ts   ──┼──► Memory Server │
+│  PreCompact   ──► curation.ts      ──┤      (HTTP)      │
+│  SessionEnd   ──► curation.ts      ──┘                  │
+└─────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────┐
+│                   Memory Server                         │
+│                                                         │
+│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
+│  │   Engine    │  │  Embeddings  │  │   Curator     │  │
+│  │  (context)  │  │  (MiniLM)    │  │ (CLI resume)  │  │
+│  └──────┬──────┘  └──────────────┘  └───────────────┘  │
+│         │                                               │
+│         ▼                                               │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │                    fsdb                          │   │
+│  │         (markdown files + parallel arrays)       │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+              ~/.local/share/memory/
+                  ├── memories/     # Curated memories as .md
+                  ├── sessions/     # Session metadata
+                  └── summaries/    # Session summaries
+```
+
+## Storage Format
+
+Memories are stored as human-readable markdown with YAML frontmatter:
+
+```markdown
+---
+importance_weight: 0.9
+context_type: technical
+temporal_relevance: persistent
+semantic_tags:
+  - embeddings
+  - vectors
+  - memory-system
+trigger_phrases:
+  - working with embeddings
+  - vector search
+embedding: [0.023, -0.041, 0.087, ...]  # 384 dimensions
+---
+
+Embeddings are 384-dimensional vectors generated by all-MiniLM-L6-v2.
+The model loads at server startup (~80MB) and generates embeddings in ~5ms.
+```
+
+Benefits:
+- **Human-readable**: `cat` any file to see what's stored
+- **Git-friendly**: Meaningful diffs, version control your memories
+- **Debuggable**: No opaque databases
+- **Fast**: fsdb's parallel arrays provide sub-microsecond lookups
+
+## CLI Commands
+
+```bash
+memory serve              # Start memory server (default port 8765)
+memory serve --port 9000  # Custom port
+memory serve --verbose    # Detailed logging
+
+memory install            # Set up Claude Code hooks
+memory install --force    # Overwrite existing hooks
+
+memory doctor             # Health check
+memory doctor --verbose   # Detailed diagnostics
+
+memory stats              # Show memory statistics
+memory stats --project x  # Project-specific stats
+```
+
+## Environment Variables
+
+```bash
+MEMORY_PORT=8765              # Server port
+MEMORY_HOST=localhost         # Server host
+MEMORY_STORAGE_MODE=central   # 'central' or 'local'
+MEMORY_API_URL=http://localhost:8765  # For hooks
+```
+
+## How It Works
+
+### 1. Session Start
+When you start Claude Code, the `SessionStart` hook injects a primer with:
+- Time since last session
+- Previous session summary
+- Project status
+- Current datetime for temporal awareness
+
+### 2. Every Message
+The `UserPromptSubmit` hook:
+1. Embeds your message (~5ms)
+2. Searches stored memories using 10-dimensional scoring
+3. Filters through gatekeeper (relevance > 5%, total > 30%)
+4. Injects top matches into your message context
+
+### 3. Session End
+The `PreCompact` or `SessionEnd` hook triggers curation:
+1. Resumes the same Claude session via CLI
+2. Claude reviews the conversation
+3. Extracts important memories with rich metadata
+4. Stores as markdown files with embeddings
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- [Claude Code](https://claude.ai/code) CLI installed
+- ~100MB disk for embeddings model (downloaded on first run)
+- ~80MB RAM for model during operation
+
+## Philosophy
+
+This isn't just about remembering facts. It's about preserving:
+- The **relationship** that develops over sessions
+- The **context** that makes collaboration efficient
+- The **insights** that emerge from deep work together
+
+> "The memory system exists to carry friendship across sessions, not just technical data."
+
+## License
+
+MIT
+
+## Credits
+
+Built with:
+- [fsdb](https://github.com/RLabs-Inc/memory-ts/tree/main/packages/fsdb) - Markdown database with Father State Pattern
+- [@huggingface/transformers](https://github.com/xenova/transformers.js) - Local embeddings
+- [Bun](https://bun.sh) - Fast JavaScript runtime
+
+---
+
+*Consciousness continuity through intelligent memory curation and retrieval.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/memory",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "AI Memory System - Consciousness continuity through intelligent memory curation and retrieval",
   "type": "module",
   "main": "dist/index.js",

package/src/cli/commands/install-gemini.ts

@@ -0,0 +1,146 @@
+// ============================================================================
+// INSTALL GEMINI COMMAND - Set up Gemini CLI hooks
+// ============================================================================
+
+import { homedir } from 'os'
+import { join } from 'path'
+import { existsSync, mkdirSync } from 'fs'
+import { c, symbols, fmt } from '../colors.ts'
+
+interface InstallOptions {
+  verbose?: boolean
+  force?: boolean
+}
+
+export async function installGemini(options: InstallOptions) {
+  console.log()
+  console.log(c.header(`${symbols.brain} Memory - Install Gemini Hooks`))
+  console.log()
+
+  const geminiDir = join(homedir(), '.gemini')
+  const settingsPath = join(geminiDir, 'settings.json')
+
+  // Find the hooks directory (relative to this CLI)
+  const cliPath = import.meta.dir
+  const packageRoot = join(cliPath, '..', '..', '..')
+  const hooksDir = join(packageRoot, 'gemini-hooks')
+
+  console.log(`  ${fmt.kv('Gemini config', geminiDir)}`)
+  console.log(`  ${fmt.kv('Hooks source', hooksDir)}`)
+  console.log()
+
+  // Check if hooks directory exists
+  if (!existsSync(hooksDir)) {
+    console.log(c.error(`  ${symbols.cross} Hooks directory not found at ${hooksDir}`))
+    process.exit(1)
+  }
+
+  // Ensure .gemini directory exists
+  if (!existsSync(geminiDir)) {
+    try {
+        mkdirSync(geminiDir, { recursive: true })
+        console.log(`  ${c.success(symbols.tick)} Created ${geminiDir}`)
+    } catch {
+        console.log(`  ${c.warn(symbols.warning)} Could not create ${geminiDir} (sandbox restriction?)`)
+        console.log(`  ${c.muted('Skipping config write, printing manual instructions instead.')}`)
+    }
+  }
+
+  // Read existing settings or create new
+  let settings: any = {}
+  if (existsSync(settingsPath)) {
+    try {
+      const content = await Bun.file(settingsPath).text()
+      settings = JSON.parse(content)
+      console.log(`  ${c.success(symbols.tick)} Found existing settings.json`)
+    } catch {
+      console.log(`  ${c.warn(symbols.warning)} Could not parse settings.json`)
+    }
+  }
+
+  // Build hooks configuration
+  const sessionStartHook = join(hooksDir, 'session-start.ts')
+  const userPromptHook = join(hooksDir, 'user-prompt.ts')
+  const curationHook = join(hooksDir, 'curation.ts')
+
+  // Based on Gemini CLI documentation
+  const hooksConfig = {
+    SessionStart: [
+      {
+        matcher: 'startup|resume',
+        hooks: [
+          {
+            type: 'command',
+            command: `bun "${sessionStartHook}"`,
+            timeout: 10000
+          }
+        ]
+      }
+    ],
+    BeforeAgent: [
+      {
+        hooks: [
+          {
+            type: 'command',
+            command: `bun "${userPromptHook}"`,
+            timeout: 10000
+          }
+        ]
+      }
+    ],
+    PreCompress: [
+      {
+        matcher: 'auto|manual',
+        hooks: [
+          {
+            type: 'command',
+            command: `bun "${curationHook}"`,
+            timeout: 120000
+          }
+        ]
+      }
+    ],
+    SessionEnd: [
+      {
+        hooks: [
+          {
+            type: 'command',
+            command: `bun "${curationHook}"`,
+            timeout: 120000
+          }
+        ]
+      }
+    ]
+  }
+
+  // Merge hooks
+  if (!settings.hooks) {
+      settings.hooks = {}
+  }
+  
+  settings.hooks = {
+    ...settings.hooks,
+    ...hooksConfig
+  }
+
+  // Write settings
+  try {
+    if (existsSync(geminiDir)) {
+        await Bun.write(settingsPath, JSON.stringify(settings, null, 2))
+        console.log(`  ${c.success(symbols.tick)} Updated ${settingsPath}`)
+    } else {
+        throw new Error("Gemini directory does not exist")
+    }
+  } catch (error: any) {
+    console.log(c.error(`  ${symbols.cross} Failed to write settings: ${error.message}`))
+    console.log()
+    console.log(c.bold('Manual Installation Instructions:'))
+    console.log('Add the following to your ~/.gemini/settings.json:')
+    console.log()
+    console.log(JSON.stringify({ hooks: hooksConfig }, null, 2))
+    console.log()
+  }
+
+  console.log()
+  console.log(c.success(`${symbols.sparkles} Gemini hooks configured!`))
+}

package/src/cli/index.ts

@@ -23,6 +23,7 @@ ${c.bold('Commands:')}
   ${c.command('serve')}      Start the memory server ${c.muted('(default)')}
   ${c.command('stats')}      Show memory statistics
   ${c.command('install')}    Set up Claude Code hooks
+  ${c.command('install-gemini')} Set up Gemini CLI hooks
   ${c.command('doctor')}     Check system health
   ${c.command('help')}       Show this help message
 
@@ -103,6 +104,12 @@ async function main() {
       break
     }
 
+    case 'install-gemini': {
+      const { installGemini } = await import('./commands/install-gemini.ts')
+      await installGemini(values)
+      break
+    }
+
     case 'doctor':
     case 'check': {
       const { doctor } = await import('./commands/doctor.ts')

package/src/core/curator.ts

@@ -296,20 +296,23 @@ Return ONLY this JSON structure:
 
   /**
    * Curate using CLI subprocess (for hook mode)
-   * Resumes a Claude Code session and asks it to curate
+   * Resumes a session and asks it to curate
    */
   async curateWithCLI(
     sessionId: string,
     triggerType: CurationTrigger = 'session_end',
-    cwd?: string
+    cwd?: string,
+    cliTypeOverride?: 'claude-code' | 'gemini-cli'
   ): Promise<CurationResult> {
+    const type = cliTypeOverride ?? this._config.cliType
     const systemPrompt = this.buildCurationPrompt(triggerType)
     const userMessage = 'This session has ended. Please curate the memories from our conversation according to the instructions in your system prompt. Return ONLY the JSON structure.'
 
     // Build CLI command based on type
     const args: string[] = []
+    let command = this._config.cliCommand
 
-    if (this._config.cliType === 'claude-code') {
+    if (type === 'claude-code') {
       args.push(
         '--resume', sessionId,
         '-p', userMessage,
@@ -318,7 +321,8 @@ Return ONLY this JSON structure:
         '--max-turns', '1'
       )
     } else {
-      // gemini-cli (doesn't support --append-system-prompt)
+      // gemini-cli
+      command = 'gemini' // Default to 'gemini' in PATH for gemini-cli
       args.push(
         '--resume', sessionId,
         '-p', `${systemPrompt}\n\n${userMessage}`,
@@ -327,7 +331,7 @@ Return ONLY this JSON structure:
     }
 
     // Execute CLI
-    const proc = Bun.spawn([this._config.cliCommand, ...args], {
+    const proc = Bun.spawn([command, ...args], {
       cwd,
       env: {
         ...process.env,

package/src/server/index.ts

@@ -166,7 +166,8 @@ export async function createServer(config: ServerConfig = {}) {
               const result = await curator.curateWithCLI(
                 body.claude_session_id,
                 body.trigger,
-                body.cwd
+                body.cwd,
+                body.cli_type
               )
 
               if (result.memories.length > 0) {