superlocalmemory

Local AI memory - no cloud, no API keys. Your AI remembers across sessions, 100% locally.

Installation

OpenCode Plugin

# npm
npm install opencode-superlocalmemory

# pnpm
pnpm add opencode-superlocalmemory

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

{
  "plugin": ["opencode-superlocalmemory"]
}

Restart OpenCode. Done.

Core Library (for custom integrations)

# npm
npm install @superlocalmemory/core

# pnpm  
pnpm add @superlocalmemory/core

import { createMemoryStore } from "@superlocalmemory/core";

const store = await createMemoryStore();
await store.add("User prefers dark mode", "user_tag", { type: "preference" });
const results = await store.search("preferences", "user_tag");

MCP Server (Claude Desktop, Cursor)

cd supermemory-local
pnpm build
node packages/mcp/dist/index.js

Add to Claude Desktop config:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/supermemory-local/packages/mcp/dist/index.js"]
    }
  }
}

Docker

cd docker
docker compose up -d
# API at http://localhost:3333

Features

Context Injection

On first message, your AI receives:

[SUPERLOCALMEMORY CONTEXT]
## User Profile
- Prefers concise responses
- Expert in TypeScript

## Project Context  
- Uses pnpm, not npm
- Build command: pnpm build
[/SUPERLOCALMEMORY CONTEXT]

This happens automatically - no prompting needed.

Keyword Detection

Say "remember", "save this", "don't forget" and the AI auto-saves:

You: "Remember that this project uses bun"
AI: [saves to project memory]

Privacy

Everything stays on your machine. No API calls, no cloud storage.

Use <private> tags to prevent sensitive data from being stored:

My API key is <private>sk-abc123</private>

Content in <private> tags is replaced with [REDACTED] before saving.

Preemptive Compaction

When context hits 80% of model limit:

1. Injects project memories into compaction prompt
2. Triggers OpenCode's summarization
3. Saves session summary as a memory

This preserves context across long sessions.

Tool Usage

The memory tool is available to your AI:

| Mode | Args | Description | |------|------|-------------| | add | content, type?, scope? | Store memory | | search | query, scope?, limit? | Semantic search | | list | scope?, limit? | List memories | | delete | memoryId | Remove memory | | profile | - | View user facts | | help | - | Show commands |

Scopes

• user - Cross-project (preferences, patterns)
• project - Project-specific (default)

Types

• preference - User preferences
• project-config - Project settings
• architecture - Design decisions
• error-solution - Bug fixes
• learned-pattern - Code patterns

Examples

# Save a preference
memory mode:add content:"User prefers dark mode" scope:user type:preference

# Search memories
memory mode:search query:"build commands"

# List project memories
memory mode:list scope:project limit:10

# Delete a memory
memory mode:delete memoryId:mem_123abc

How It Works

| Component | Tech | Purpose | |-----------|------|---------| | Vector DB | Orama | Fast embedded search | | Embeddings | Transformers.js | Local ML, no API | | Storage | JSON file | ~/.superlocalmemory/memories.json |

First query downloads the embedding model (~30MB). Subsequent queries are instant.

Configuration

Create ~/.config/opencode/superlocalmemory.json:

{
  "dataPath": "~/.superlocalmemory",
  "similarityThreshold": 0.6,
  "maxMemories": 5,
  "maxProjectMemories": 10,
  "compactionThreshold": 0.8,
  "embeddingModel": "Xenova/all-MiniLM-L6-v2",
  "debug": false
}

| Option | Default | Description | |--------|---------|-------------| | dataPath | ~/.superlocalmemory | Where memories are stored | | similarityThreshold | 0.6 | Min similarity for search results | | maxMemories | 5 | Max memories injected per request | | maxProjectMemories | 10 | Max project memories listed | | compactionThreshold | 0.8 | Context usage ratio that triggers compaction | | embeddingModel | Xenova/all-MiniLM-L6-v2 | Local embedding model (or "none") | | debug | false | Enable debug logging to ~/.superlocalmemory.log |

Development

pnpm install
pnpm build
pnpm test

vs Supermemory

| Feature | superlocalmemory | supermemory | |---------|------------------|-------------| | Privacy | 100% local | Cloud API | | API Key | Not needed | Required | | Cost | Free | Paid | | Setup | Clone & run | Install + signup | | Embeddings | Local (Transformers.js) | Cloud | | Context injection | Yes | Yes | | Keyword detection | Yes | Yes | | Privacy tags | Yes | Yes | | Preemptive compaction | Yes | Yes |

Architecture

packages/
  core/           # Memory engine (Orama + embeddings)
  mcp/            # MCP server (stdio + HTTP)
  opencode-plugin/# OpenCode integration
docker/           # Docker deployment

License

MIT