🌟 What is Super Memory?

Super Memory is an OpenCode plugin that gives your AI coding assistant permanent, cross-session memory. It automatically learns from every interaction — your tech stack, decisions, preferences, and project context — and recalls them in future sessions.

No more repeating yourself. Every session builds upon the last.

✨ Key Features

• 🧠 Automatic Learning — Every message, command, and tool result is analyzed and stored
• 🔍 Smart Recall — Relevant memories are injected into the system prompt on each session
• 📂 Tech Stack Detection — Automatically recognizes languages, frameworks, databases, and tools
• 📝 Decision Tracking — Captures architectural decisions and preferences
• 👤 User Profiling — Learns your working style, preferences, and patterns
• 🔧 Custom Tools — Query, save, and manage memories directly from chat
• 🔄 Cross-Platform — Works on Linux, macOS, Windows, and Termux (Android)
• 📦 Auto-Installer — Smart setup that detects and configures PostgreSQL automatically

🆕 v2.0 Features

• 🤖 AI-Powered Extraction — Uses LLM for semantic understanding of conversations
• 🎯 Context-Aware Recall — Injects memories relevant to current session context
• 📊 Pattern Detection — Identifies recurring workflows and habits across sessions
• 💡 Smart Suggestions — Provides contextual workflow recommendations
• 📈 User Profile — Builds evolving profile with preferences and experience level
• 🏗️ Project Context — Automatic detection of architecture and conventions
• 🔄 Session Summarization — Auto-generates session summaries with LLM
• 🧮 Embeddings Support — Semantic search via vector similarity (optional)

🏗️ Architecture

graph TB
    subgraph OpenCode["OpenCode"]
        direction TB
        subgraph Plugin["Super Memory Plugin"]
            direction TB
            Hooks["Hooks<br/><br/>chat.message<br/>event<br/>tool.execute.after<br/>system.transform<br/>session.compacting"]
            Tools["Tools<br/><br/>mem_save<br/>mem_search<br/>mem_forget<br/>mem_stats"]
            API["Express API<br/><br/>GET /health<br/>POST /api/memory<br/>GET /api/memory/:id<br/>PUT /api/memory/:id<br/>DELETE /api/memory/:id<br/>GET /api/memory/search<br/>GET /api/memory/stats"]
            Processor["Memory Processor<br/><br/>Extract → Store → Recall<br/><br/>Dedup · FTS · Ranking"]
        end
        DB[("PostgreSQL<br/>ultra_memory")]
    end

    Hooks --> Processor
    Tools --> Processor
    API --> Processor
    Processor --> DB

    style OpenCode fill:#1a1a2e,color:#fff,stroke:#16213e
    style Plugin fill:#0f3460,color:#fff,stroke:#16213e
    style DB fill:#1b4332,color:#fff,stroke:#2d6a4f
    style Hooks fill:#1a5276,color:#fff,stroke:#2980b9
    style Tools fill:#1a5276,color:#fff,stroke:#2980b9
    style API fill:#1a5276,color:#fff,stroke:#2980b9
    style Processor fill:#2471a3,color:#fff,stroke:#3498db

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• PostgreSQL (auto-installed if missing)
• OpenCode with plugin support

Installation

# Clone the repository
git clone https://github.com/luftwaffe66/Super-Memory.git
cd Super-Memory

# Install dependencies
npm install

# Run the installer (detects/installs PostgreSQL, creates DB, runs migrations)
npm run install:plugin

# Build the plugin
npm run build

OpenCode Configuration

Add the plugin to your ~/.config/opencode/opencode.jsonc:

{
  "plugin": [
    "super-memory"
  ]
}

Note: For local development, use npm link or a local path reference.

🛠️ Memory Tools

Super Memory registers four custom tools accessible from your OpenCode chat:

| Tool | Description | Example | |------|-------------|---------| | mem_save | Save an explicit memory | mem_save(key="framework", content="Using React with TypeScript") | | mem_search | Search stored memories | mem_search(query="React components") | | mem_forget | Delete a specific memory | mem_forget(id="uuid-here") | | mem_stats | View memory statistics | mem_stats() |

🧠 How It Works

Automatic Learning

Every message you send is processed through multiple extractors:

1. Tech Stack Detector — Identifies languages, frameworks, and tools mentioned
2. Decision Parser — Captures architectural and design decisions
3. Preference Analyzer — Learns your working style and preferences
4. Pattern Recognizer — Identifies recurring workflows and commands

Smart Recall

When a new session starts, Super Memory:

1. Searches for memories relevant to the current conversation
2. Ranks them by importance and relevance
3. Injects the most relevant memories into the system prompt
4. Updates access timestamps to track usage patterns

Data Storage

All memories are stored in PostgreSQL with:

• Full-text search via tsvector indexes for fast retrieval
• JSONB columns for flexible metadata
• Automatic deduplication to prevent memory bloat
• Importance scoring (1-5) to prioritize critical information

📁 Project Structure

Super-Memory/
├── package.json              # Plugin manifest
├── tsconfig.json             # TypeScript configuration
├── scripts/
│   └── install.sh            # Shell installer wrapper
├── src/
│   ├── index.ts              # Plugin entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── config.ts             # Environment configuration
│   ├── db/
│   │   ├── connection.ts     # PostgreSQL connection pool
│   │   ├── queries.ts        # Database CRUD operations
│   │   ├── migrations.ts     # Schema migration runner
│   │   └── migrations/
│   │       └── 001_initial.sql  # Initial schema
│   ├── memory/
│   │   ├── index.ts          # Module barrel
│   │   ├── extractor.ts      # Pattern extraction (regex/heuristic)
│   │   ├── llm-extractor.ts  # 🆕 AI-powered extraction via LLM
│   │   ├── embeddings.ts     # 🆕 Semantic search with embeddings
│   │   ├── pattern-detector.ts  # 🆕 Cross-session pattern detection
│   │   ├── user-profile.ts   # 🆕 Evolving user profile
│   │   ├── project-context.ts  # 🆕 Automatic project context
│   │   ├── suggestions.ts    # 🆕 Workflow suggestions
│   │   ├── store.ts          # Memory storage with dedup
│   │   ├── search.ts         # Memory search and formatting
│   │   └── processor.ts      # Core orchestrator
│   ├── server/
│   │   ├── index.ts          # Express app factory
│   │   ├── schemas.ts        # Zod validation schemas
│   │   ├── middleware/
│   │   │   ├── async-handler.ts  # Async error wrapper
│   │   │   └── error-handler.ts  # Global error handler
│   │   └── routes/
│   │       ├── health.ts     # Health check endpoint
│   │       └── memory.ts     # Memory CRUD REST API
│   ├── hooks/
│   │   ├── index.ts          # Hook barrel exports
│   │   ├── message-handler.ts  # Chat message processing
│   │   ├── event-handler.ts  # Session lifecycle tracking
│   │   ├── tool-handler.ts   # Tool output capture
│   │   ├── system-transform.ts  # Context-aware memory injection
│   │   └── session-compactor.ts  # Session compaction hints
│   ├── tools/
│   │   └── definitions.ts    # Custom tool schemas
│   └── installer/
│       └── index.ts          # Cross-platform installer
└── tests/                    # Test suite

🌐 Cross-Platform Support

Super Memory's auto-installer handles multiple environments:

| Platform | Package Manager | PostgreSQL Install | |----------|---------------|-------------------| | Linux | apt, dnf, yum, apk | Auto-detected, installs if missing | | macOS | brew | brew install postgresql@17 | | Termux (Android) | pkg | pkg install postgresql | | Windows | — | Manual setup (instructions provided) |

The installer never hardcodes sudo — it detects whether it's available and uses it only when necessary.

⚙️ Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | UM_DB_HOST | localhost | PostgreSQL host | | UM_DB_PORT | 5432 | PostgreSQL port | | UM_DB_NAME | ultra_memory | Database name | | UM_DB_USER | System user | Database user | | UM_DB_PASSWORD | Empty | Database password | | UM_MAX_INJECTIONS | 5 | Max memories to inject | | UM_MIN_IMPORTANCE | 2 | Min importance level | | UM_LLM_ENABLED | true | Enable AI extraction | | UM_LLM_MODEL | gpt-4o-mini | LLM model to use | | UM_LLM_API_KEY | Empty | API key for LLM | | UM_LLM_BASE_URL | https://api.openai.com/v1 | LLM API base URL | | UM_LLM_SUMMARIZE | true | Enable session summarization |

OpenCode Configuration

Add to your ~/.config/opencode/opencode.json:

{
  "plugin": ["super-memory"],
  "lsp": true
}

📄 License

This project is licensed under the MIT License.