local-memory

100% local, OpenAI-compatible memory layer for AI agents. On-device embeddings via Ollama, SQLite + sqlite-vec for vector search, zero cloud round-trips. Drop-in for any code that already speaks /v1/embeddings.

Why this exists

Every AI-agent memory repo today — Supermemory, claude-mem, mem0, Graphiti — assumes you'll call OpenAI for embeddings and often a hosted vector DB on top. That means three things for a solo dev or privacy-conscious user:

1. Every agent interaction has a network round-trip.
2. A paid API bill scales with your agent's usage.
3. Your memory lives off-device, off-machine, in someone else's cloud.

local-memory is the opposite: a single Node process, one SQLite file on disk, embeddings via a local Ollama instance running on your own laptop. It exposes an OpenAI-compatible /v1/embeddings endpoint so any existing client that accepts a baseURL override just works — no SDK swap, no code rewrite. It also exposes a small first-class memory API (POST /memory, /memory/search, namespaces, export, import) for when you want more than just embeddings.

30-second demo

# Prereq: Ollama running with an embedding model pulled
ollama pull nomic-embed-text
ollama serve &   # listens on 127.0.0.1:11434

# Start the memory server
npx -y @swarmclawai/local-memory start

# Point your OpenAI client at it
export OPENAI_BASE_URL=http://localhost:3456/v1
export OPENAI_API_KEY=not-used

# From another shell, store and search memories
npx -y @swarmclawai/local-memory add "User prefers kebab-case for slugs"
npx -y @swarmclawai/local-memory search "casing conventions"

Install

pnpm add -g @swarmclawai/local-memory
# or
npm i -g @swarmclawai/local-memory
# or run on demand
npx -y @swarmclawai/local-memory --help

Providers

| Provider | Default model | Dim | When to use | |---|---|---|---| | ollama (default) | nomic-embed-text | 768 | You have ollama serve running locally | | mock | deterministic hash | 64 | Unit tests, offline demos, zero-dep fallback |

Override the embedder with --provider, --model, --dim, and --embed-base-url.

Commands

| Command | Purpose | |---|---| | local-memory start | Start the HTTP server on port 3456 | | local-memory add <text> | Embed and store a memory (-n <namespace>, --metadata '{...}') | | local-memory search <query> | Semantic search (-n <namespace>, -k <limit>) | | local-memory namespaces | List namespaces + counts | | local-memory export | Dump memories as JSONL on stdout | | local-memory import <file> | Re-embed every line from a JSONL file | | local-memory help-agents | Print the full machine-readable catalog |

Every command accepts --json and returns a one-line JSON envelope. Exit codes: 0 success, 1 user error, 2 internal error.

HTTP endpoints (when started)

| Endpoint | Purpose | |---|---| | GET / | Service info + dim + embedder id | | POST /v1/embeddings | OpenAI-compatible drop-in — body {input: string \| string[]} | | POST /memory | Store a memory ({text, namespace?, metadata?}) | | GET /memory/:id | Fetch a memory | | DELETE /memory/:id | Remove a memory | | POST /memory/search | Semantic search ({query, namespace?, limit?}) | | GET /namespaces | List namespaces |

Drop-in for OpenAI clients

Any OpenAI SDK that supports baseURL works out of the box. Example with the Node SDK:

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "http://localhost:3456/v1",
  apiKey: "not-used",
});
const res = await client.embeddings.create({
  model: "anything",
  input: "the quick brown fox",
});

How it works

• Embeddings come from a local Ollama process — nothing leaves your machine.
• Vectors are stored in a plain SQLite file via sqlite-vec. Default path: ~/.local-memory/memory.db.
• Search uses sqlite-vec's MATCH operator for k-nearest-neighbor retrieval. Results come back with a normalized similarity score in (0, 1] — higher is better.
• Namespaces are just a column — free per-app or per-agent memory isolation.

How it compares

| | local-memory | Supermemory | claude-mem | mem0 | Graphiti | |---|---|---|---|---|---| | Runs 100% offline | ✅ | ❌ | partial | ❌ | ❌ | | OpenAI-compatible drop-in | ✅ | ❌ | ❌ | ❌ | ❌ | | Single SQLite file | ✅ | ❌ | ❌ | ❌ | ❌ | | Pluggable embedder | ✅ | ❌ | ❌ | partial | partial | | Agent-driven CLI | ✅ | — | partial | partial | — |

Built for coding agents

Every swarmclawai CLI follows the same agent conventions:

• --json everywhere, one-line envelope on stdout
• Stderr for logs, stdout for data
• Stable exit codes: 0 / 1 / 2
• Non-interactive by default
• local-memory help-agents returns the entire command catalog as JSON

See AGENTS.md for the full machine-readable reference.

Roadmap

• MCP adapter — expose memory tools to any MCP-compatible agent (Claude Code, Cursor, Cline, Aider, etc.)
• Apple Intelligence + MLX providers for macOS
• Gemini Nano provider for Chrome/Pixel
• Incremental compaction (TTL + importance-weighted pruning)
• Hybrid BM25 + vector retrieval
• Encryption-at-rest flag for the DB

Contributing

See CONTRIBUTING.md.

License

MIT