# Brain cartridges for AI agents.

A neuromorphic substrateA physics-based memory layer inspired by biological neural networks — Hopfield attractors, Hebbian learning, content-addressable recall.Deep dive → that plugs in via MCPModel Context Protocol — an open standard by Anthropic that lets AI agents connect to external tools through a universal interface.Deep dive →.

No LLM in the pipeline.

Get Started View on GitHub
4.8M entries indexed
$0 per query
0 LLM calls

## What is Membot?

Membot is an MCP serverA process that exposes tools to AI agents via the Model Context Protocol. The agent discovers and calls tools without custom integration code.Deep dive → that gives AI agents long-term, searchable memory. Think of it as brain cartridges — self-contained memory modules that you can mount, search, swap, and share.

### Mount

Load a brain cartridge — a pre-built memory archive — and make its contents instantly searchable. Cartridges are portable: share them, version them, swap them.

### Search

Hybrid retrieval blends cosineMeasures the angle between two vectors in high-dimensional space. Captures semantic similarity — how close two meanings are.Deep dive → similarity, HammingCounts differing bits between two binary strings using XOR + popcount. Extremely fast — runs in nanoseconds on modern CPUs.Deep dive → distance, and keyword boosting into a single ranked result. No LLM required.

### Store & Swap

Add new memories on the fly. Mount different cartridges for different tasks. Each cartridge is verified with SHA-256A cryptographic hash function that produces a unique 256-bit fingerprint. Any changed byte produces a completely different hash.Deep dive → integrity checks.

## How search works

Every query passes through a three-signal pipeline. Each signal catches what the others miss.

### Signal weights

CosineMeasures semantic similarity by computing the angle between embedding vectors. Weight: 70%.Deep dive →
70%
HammingBinary comparison via XOR + popcount on sign-zero encoded vectors. Weight: 30%.Deep dive →
30%
KeywordAdditive boost for exact query term matches found in the passage text. +0.03 per term hit, capped at +0.12. Not a blend weight — applied after cosine/Hamming ranking.
boost

### The pipeline

Query → Nomic embednomic-ai/nomic-embed-text-v1.5 — a 768-dimensional embedding model (~270 MB) that runs locally. No API calls needed.Deep dive → → Sign-zero encodeConverts 768 floats to 768 packed bits (96 bytes): positive → 1, else → 0. 32x compression while preserving semantic fingerprint.Deep dive → → Cosine + Hamming + Keyword → Blended rank

### The binary trick

Sign-zero encodingPositive values become 1, everything else becomes 0. Pack 8 bits into one byte. A 768-float vector (3,072 bytes) becomes 96 bytes — 32x smaller. Based on SimHash (Charikar, 2002).Deep dive → collapses each embedding dimension to a single bit: positive → 1, else → 0. Then pack 8 bits into a byte. Membot uses 768-dimensional embeddings (Nomic v1.5), so each vector shrinks from 3,072 bytes to 96 bytes — 32x smaller. Comparison becomes XOR + popcountXOR highlights differing bits. Popcount counts them. Both are single CPU instructions — the comparison runs in nanoseconds.Deep dive → — a single CPU instruction per chunk.

### Accuracy

Method | Correlation with full cosine
--- | ---
Hamming on sign-zero (768-dim Nomic) | Pearson r = 0.891
Full float cosine | r = 1.000

Measured on 25K Nomic v1.5 embeddings. The sign-zero binary code preserves ~79% of the variance of full cosine similarity.

### Hamming-only mode

For maximum speed, Membot can search using only Hamming distance on the binary index. This skips the float cosine pass entirely, making search over millions of entries nearly instantaneous on commodity hardware.

### Neuromorphic layer

Beyond search, Membot includes a neuromorphic latticeA grid of simulated neurons that can reconstruct memories from partial inputs — like remembering a whole song from the first few notes. Uses Hopfield attractor dynamics and Hebbian learning.Deep dive → — a 64×64 grid of neural regions with Hebbian weightsConnection strengths that grow when neurons activate together — "neurons that fire together wire together" (Donald Hebb, 1949).Deep dive →, Mexican-hat inhibitionA connectivity pattern where nearby neurons excite each other while distant ones inhibit. This sharpens recall by suppressing noise and focusing activation — the same mechanism used in biological visual cortex.Deep dive →, and attractor dynamicsThe network settles into stable states (attractors) like a ball rolling into valleys on a landscape. Partial or noisy input converges to the nearest stored memory.Deep dive →. This enables noise-tolerant recall and cross-modal association.

### Cross-modal association

The neuromorphic layer can bind text, image (CLIPContrastive Language-Image Pre-training (OpenAI, 2021). Maps images and text into the same vector space, enabling cross-modal search.Deep dive →), and audio (CLAPContrastive Language-Audio Pre-training. Maps audio and text into the same vector space, enabling sound-to-text and text-to-sound retrieval.Deep dive →) embeddings together via Hebbian weight matrixA learned matrix of connection strengths between neural regions. Trained with Hebb's rule: co-activated neurons strengthen their connections.Deep dive → training, so a text query can retrieve images and a sound can retrieve text.

## Brain cartridges

A brain cartridge is a self-contained, portable memory archive. Two formats are supported:

File | Format | Contents
--- | --- | ---
`.cart.npz` | Standard | Vectors + texts + metadata in a single compressed archive
`_index.npz` + `_text.db` | Split | Vectors in NumPy, texts in SQLiteA self-contained, serverless SQL database engine. Ships with Python. Enables paged text access without loading everything into RAM.Deep dive → — scales to millions
`_brain.npy` | Neuromorphic | Hebbian weight matrix for cross-modal recall
`_manifest.json` | Manifest | SHA-256 hashes, build metadata, integrity verification

### Split cart format

At scale (millions of entries), the split format keeps the vector index in RAM for fast search while storing raw text on disk in SQLite. Text lookups are ~1 ms. This lets you search 4.8M entries on an affordable consumer host (currently $28/month on DigitalOcean for 4 GB).

## Why Membot?

Feature | Cloud vector DBs (Pinecone, Weaviate, etc.) | Membot
--- | --- | ---
LLM dependency | None for search (embedding model required for ingest) | None for search (same embedding model for ingest)
Hosting | Managed cloud service (subscription pricing) | Self-hosted — portable files you own
Cost at 4.8M entries | $70–200+/mo depending on provider | $28/mo VPS (split cart format)
Physics layer | None | Hopfield attractors, Hebbian learning, noise-tolerant recall
Cross-modal | Supported via multi-modal embeddings | Native Hebbian binding — text + image + audio in one substrate
Portability | Vendor-specific APIs and formats | Cartridge files — copy, share, version like any file

Memory should be a physics problem, not a language problem. Bits, not tokens.

## Get started

### 1. Install

# Clone and install from source git clone https://github.com/project-you-apps/membot.git cd membot pip install -r requirements.txt

### 2. Run

# Local (stdio) — for Claude Code, OpenClaw, local agents python membot_server.py # Remote (HTTP) — for any MCP client over the network python membot_server.py --transport http --port 8000

### 3. Connect your agent

### Claude Code (local)

// .mcp.json { "mcpServers": { "membot": { "command": "membot", "args": ["serve"] } } }

### Claude Code (remote)

// .mcp.json { "mcpServers": { "membot": { "type": "sse", "url": "https://your-server/sse" } } }

### 4. Use it

# Search memory membot_search query="how does the trust tensor work" # Store a memory membot_store content="The trust tensor maps agent reliability across domains" # Mount a cartridge membot_mount path="/data/web4-docs.cart.npz"

### 5. Build cartridges

# From any folder of documents (.txt, .md, .pdf, .docx) python cartridge_builder.py ./my-docs/ --name my-knowledge # With lattice training (GPU, enables associative recall) python cartridge_builder.py ./my-docs/ --name my-knowledge --train # Single PDF python cartridge_builder.py paper.pdf --name paper

The repo includes a pre-built cartridge of Attention Is All You Need (Vaswani et al., 2017) — mount it and start searching immediately. For a richer GUI experience, use Vector+ Studio.

## Available tools

Tool | Description
--- | ---
`membot_search` | Search mounted memory with hybrid retrieval
`membot_store` | Store a new memory entry
`membot_mount` | Mount a brain cartridge
`membot_unmount` | Unmount the current cartridge
`membot_status` | Show server status and mounted cartridge info
`membot_list` | List available cartridges
`membot_recall` | Neuromorphic recall (physics-based retrieval)
`membot_verify` | Verify cartridge integrity via SHA-256
`membot_stats` | Show search and performance statistics

## Deployment options

### Public dispensary

A shared Membot server with pre-built cartridges. Connect any MCP-compatible agent and start searching immediately.

### Team server

Run Membot on your own infrastructure. Mount team-specific cartridges. SSE transport for remote agents.

### Personal server

Run locally via stdio. Your memories stay on your machine. Zero network dependency.

### Live deployment

The public dispensary currently serves 4.8M entries on a single $28/month DigitalOcean droplet (4 GB RAM, 80 GB disk) — no GPU, no cloud vector database, no LLM API calls.

Cart | Entries | Index (RAM) | Text (disk)
--- | --- | --- | ---
arXiv abstracts | 2,400,000 | 360 MB | 3.5 GB
Wikipedia articles | 2,400,000 | 380 MB | 1.3 GB

### Production considerations

Membot is designed for simplicity, not managed infrastructure. Some things to know:

- Auth — API key auth via `MEMBOT_API_KEY` environment variable. One key per server instance.
- Concurrency — multiple agents can search simultaneously via session isolation (up to 50 concurrent sessions).
- Durability — cartridges are files on disk. Back them up like any file. SHA-256 manifests verify integrity.
- Recovery — systemd auto-restarts on crash. Clients reconnect with fresh sessions.
- Read-only by default — `memory_store` and `save_cartridge` are disabled unless you pass `--writable`.
- No HA/replication built in — for high availability, run multiple instances behind a load balancer with shared cartridge storage.

## Concept deep dives

Each concept page explains the theory, the math, and how Membot uses it.

### Cosine Similarity

Measuring meaning by measuring angles.

### Hamming Distance

Binary comparison via XOR + popcount.

### Sign-Zero Encoding

33x compression that preserves meaning.

### Embeddings

Turning text into searchable vectors.

### Neuromorphic Substrate

Hopfield networks and attractor dynamics.

### Hebbian Learning

Neurons that fire together wire together.

### MCP

The USB port for AI tools.

### CLIP

Images and text in the same space.

### CLAP

Audio and text in the same space.

### SHA-256

Cryptographic integrity verification.

### SQLite

Serverless database for text storage.