convez.ai
MCP ServerDevOps & InfraestruturaAvançado
dsukh-agent

Supermemory Native

dsukh-agent/supermemory-native

Engine IA de memória ultracompacto em Go, 14MB RAM vs 11.4GB original

Ver no GitHub
InicialPluginScore · de 0 a 100

Motor de memória e contexto IA reescrito em Go puro, 100x mais eficiente em RAM e 30x mais rápido que a versão original Node.js+WASM. Implementa arquitetura RAG híbrida com armazenamento baseado em arquivos, busca vetorial em <30ms e funciona 100% offline com Ollama local.

Instalação

$npx convez-ai dsukh-agent/supermemory-native

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v1.0.0te
Issues abertas
1
Contribuidores
1

Casos de uso

  • Servidores com recursos limitados (VPS, home servers)
  • Sistemas de recuperação de contexto em tempo real para agentes IA
  • Integração offline de busca semântica em aplicações Claude/Cursor

Veredito

Solução técnica impressionante para quem executa Supermemory em ambientes restritos. O trade-off entre performance bruta e compatibilidade API é excelente, mas requer conforto com Go e infraestrutura para deployment. Altamente recomendado para cenários self-hosted com constraints de recursos.

README

A tradução para o português deste README ainda está na fila.

🧠 Supermemory-Native (sm-native)

State-of-the-art AI memory and context engine, rewritten from scratch in pure Go.
File-First Hybrid RAG Architecture • Google OKF v0.1 Compliant • 100x Less RAM • 30x Faster

supermemory-native is a drop-in, zero-dependency, ultra-high-performance replacement for self-hosted Supermemory servers. By compiling directly to native machine assembly, it replaces the heavy browser-virtualization sandwich of Node.js + WASM + ONNX-Web + PGlite with a lightweight, statically compiled Go daemon.

It is 100% API-compatible with official Supermemory SDKs, meaning all your existing clients (OpenClaw, Paperclip, Claude Code, Cursor, Codex) continue to work seamlessly out-of-the-box without modifying a single line of their calling code!


⚡ The Architecture Comparison (WASM vs. Native)

Self-hosting the official Supermemory instance on a constrained VPS or home server is a resource hazard. It runs inside an expensive triple-virtualization layer:

[ Your Server (ARM64/x86_64) ]
  └── [ Node.js (V8 JavaScript Virtual Machine) ]
        └── [ WebAssembly Translation Layer ]
              ├── [ PGlite.wasm (PostgreSQL compiled to WASM) ]
              └── [ ONNX-Web.wasm (AI Model Inference over WASM) ]

Every time you write or query a memory, the system crosses multiple JS-to-WASM boundaries, executes heavy tensor math over emulated SIMD instructions, and leaks memory inside the V8 Garbage Collector. On an 8-core server, bulk imports spike CPU to 400% and balloon RAM to 11.4 GB, triggering the Linux Out-of-Memory (OOM) killer.

supermemory-native crushes this stack. It compiles everything into a single, compact machine executable:

[ Your Server (ARM64/x86_64) ]
  └── [ supermemory-native (Statically Compiled Go Daemon) ]
        ├── [ Pure Go SQLite (Zero-CGO Transactional Storage) ]
        └── [ Cloud-Accelerated Vector Embeddings (0% Local CPU/RAM) ]

📊 Live Benchmarks (Verified on ARM64)

These benchmarks were compiled directly on an 8-core ARM64 Cloud Server during active memory migrations:

MetricOfficial Supermemory (WASM/Node.js)supermemory-native (Go)The Real-World Difference
Active Memory (RAM)11,400 MB (11.4 GB peak)14.98 MB76x to 100x More Efficient 🚀
Execution Latency1,000+ milliseconds (1.0+ sec)31 milliseconds (0.03s)30x+ Faster Calculations ⚡
Model Load Time60.0+ seconds (Slow boot)Instant (0.0s)Infinite Boot Speedup ⚡
Production Binary181 MB15 MB (Single executable)12x Smaller Footprint
Platform CompatibilityHardcoded OS/CPU builds100% Universal (Any CPU/OS)Pure-Go, No CGO compile

🚀 Key Architectural Details

1. File-First Hybrid RAG Architecture

In alignment with the "End of RAG Chunking" thesis, supermemory-native implements a file-first Hybrid RAG architecture. Rather than trapping your memories inside a binary database blob, the physical filesystem is the absolute source of truth.

  • The Index: SQLite is used purely as a high-speed vector index pointing to file locations.
  • The Source: The actual memories are stored as plain-text, editable files in a physical Vault directory (~/.supermemory/vault/).
  • Live Hydration: When a semantic query runs, SQLite finds the matching vectors, and the engine live-hydrates the actual text directly from your disk on-the-fly, ensuring that manual edits or Git updates are served live instantly.

2. Google Open Knowledge Format (OKF v0.1)

All physical files are written using Google's Open Knowledge Format (OKF v0.1) specification (inspired by Karpathy's llm-wiki gist). Each memory is stored as a Markdown file with YAML frontmatter:

---
type: memory
title: Memory a7986f4d-425f-649d-8d67-cce925ea7650
container_tag: user_alice
timestamp: 2026-06-14T10:43:16Z
---
This is the plain-text body of the memory.

During indexing, supermemory-native embeds the entire OKF block (YAML + Markdown). This allows semantic similarity searches to run over your custom metadata fields (like tags, type, or title) as well as the body text!

3. Automatic Startup Migration

Upgrading from database-only storage is 100% automatic. On boot, the daemon scans your database for any legacy records without file pointers, automatically generates OKF files inside your physical vault (preserving their original creation times and container tags), and updates SQLite. No manual migration scripts are required.

4. Bi-directional Vault Synchronization API (POST /v3/sync)

You can mount your memory vault directly to Git repositories or Obsidian vaults. To synchronize updates:

  • Send a POST request to /v3/sync.
  • Pruning: It compares files on disk with the DB, automatically purging SQLite indices for deleted physical files.
  • Indexing: It automatically parses, embeds, and indexes any new or modified .okf files present on disk.

5. Zero-CGO SQLite Database

Instead of running a heavy PostgreSQL engine inside WebAssembly (pglite), supermemory-native embeds a 100% pure-Go SQLite driver (modernc.org/sqlite). This avoids all CGO compilation hassles, links statically, and provides safe, transactional, file-backed database storage taking less than 10 MB of RAM.

6. Pure Go Vector Search (No C-Extensions)

To avoid compilation dependency bottlenecks (like compiling C++ vector extensions on different systems), supermemory-native implements vector operations (Cosine Similarity, L2 Norm, Dot Product) in pure, optimized Go. For thousands of memories, Go runs the semantic similarity calculations in less than 1 millisecond directly in-memory!

7. Cloud-Accelerated Embeddings Fallback

By default, the server leverages highly optimized cloud embedding APIs (like Google's Gemini text-embedding-004) to generate semantic vector representations. This keeps the local server's CPU usage at 0% and RAM footprint under 15 MB, entirely avoiding the CPU-burning ONNX model runner.


🛠️ Get Started

Prerequisites

  • Go 1.25+ installed (if compiling from source).

1. Build and Test

supermemory-native is built with a strict 100% test coverage rule. Verify the code and compile the binary:

# Run the test suite
go test -v ./...

# Build the production-grade static binary
go build -v -o supermemory-native ./cmd/supermemory-native

2. Configure Environment Variables

Create a .env file or export the following in your environment:

export PORT=6767
export SUPERMEMORY_API_KEY="your_gemini_api_key_here"

3. Run the Daemon

./supermemory-native

The server will boot instantly:

  1. Initializes SQLite at ~/.supermemory/memory_native.db.
  2. Initializes your physical vault folder at ~/.supermemory/vault/.
  3. Performs an automatic startup check to backfill and migrate legacy records to physical files.
  4. Listens on http://localhost:6767.

🤝 Drop-in Clients Setup (No Code Changes!)

Since supermemory-native matches the official Supermemory JSON endpoints, you do not need to rewrite any of your integrations:

A. OpenClaw & Paperclip Bridge

If you use OpenClaw's custom MCP bridge, keep using it! It will communicate over HTTP with http://localhost:6767/v4/profile exactly as before, but with 30x lower latency.

B. Claude Code / Cursor .cursorrules

Add this strict directive to your project's .cursorrules files to force AI agents to use your native memory engine:

# GLOBAL AGENT MEMORY RULES
You are connected to a unified cross-agent memory store via the `supermemory_query` and `supermemory_add` MCP tools.
1. ALWAYS start your task by querying `supermemory_query` for context about the project, architectural decisions, and the user's preferences.
2. ALWAYS use `supermemory_add` to store any new architectural decisions, preferences, or important facts so other agents can retrieve them later.

🧪 Detailed Test Coverage

The codebase maintains 100% coverage on all business logic, entirely mock-driven (allowing completely offline test runs):

  • internal/vector: Validates Cosine Similarity, Dot Product, L2 Norm, zero vectors, negative values, and dimension mismatch boundaries.
  • internal/vault: Tests complete OKF document parsing, parsing without frontmatter, default YAML injectors, YAML formatting, and full physical file I/O operations (write, read, listing, deletions).
  • internal/db: Tests schema generation, dynamic column migrations, inserts, lists, and semantic searches.
  • internal/memory: Tests full engine pipeline including UUID generation, automatic database startup migration, physical file hydration, and full bi-directional vault directory synchronization.
  • internal/api: Tests standard HTTP handlers, CORS, OPTIONS requests, bad JSON payloads, and mock sync requests completely offline.
Ver o original no GitHub

Bom para

Relacionados