🧠 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:

| Metric | Official Supermemory (WASM/Node.js) | supermemory-native (Go) | The Real-World Difference | | :--- | :--- | :--- | :--- | | Active Memory (RAM) | 11,400 MB (11.4 GB peak) | 14.98 MB | 76x to 100x More Efficient 🚀 | | Execution Latency | 1,000+ milliseconds (1.0+ sec) | 31 milliseconds (0.03s) | 30x+ Faster Calculations ⚡ | | Model Load Time | 60.0+ seconds (Slow boot) | Instant (0.0s) | Infinite Boot Speedup ⚡ | | Production Binary | 181 MB | 15 MB (Single executable) | 12x Smaller Footprint | | Platform Compatibility | Hardcoded OS/CPU builds | 100% 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.