Remember the owner. Keep each pet relationship separate. Stay on the device.
A Rust core in one SQLite file — memory that survives restarts, model changes, and network loss.
Run the complete memory demo with local ONNX inference and no API key. Requires macOS or Linux (x64 / arm64), Rust, Python 3, and curl. The first run downloads dependencies and a model.
git clone --branch main https://github.com/vibeinging/MemMe.git
cd MemMe
bash demos/rest-demo.shThe script downloads and configures VexDB-Lite and ONNX Runtime, builds the server, and keeps the model cache with the demo data. The v0.1.2 source archive predates these scripts; use main as shown above.
PASS wrote memories for an owner and two pets
PASS Momo sees his promise
PASS no leak to Luna
PASS Luna sees her toy
PASS owner-global allergy visible to Momo
PASS after restart, Momo still remembers
PASS isolation survives restartsThese are the expected results. The script stops the server completely, restarts it on the same SQLite file, and checks memory and isolation again. Any failure exits with an error.
bash demos/rest-demo.sh
# If port 18070 is busy:
MEMME_DEMO_PORT=18071 bash demos/rest-demo.shData and the model cache stay in ~/.cache/memme-demo. Later runs reuse them; loading the model still takes time. Startup logs are in server.log in that directory. The default startup timeout is 600 seconds; override it with MEMME_DEMO_START_TIMEOUT.
For individual API calls, follow the manual REST guide. Prefer Node.js? npm install @wjmwjmwb/memme (macOS / Linux) — see the Node.js guide.
Three behaviors you can verify yourself in the quick start above.
Everything durable lives in one SQLite file. Quit the process, reopen the same database, and the recall results are unchanged — even after switching to a different model.
Owner-global facts are shared across the owner’s pets; each pet’s relationship memory is scoped to that pet. Ask as Momo, and another pet’s promise never appears.
Expired and superseded facts are filtered before they can reach a reply, while the full change history stays auditable in the same file.
From raw conversation to structured knowledge, step by step through the engine.
Four independent retrieval channels fused with adaptive Reciprocal Rank Fusion.
Query embedding → cosine similarity against all memory embeddings. Semantic understanding of intent.
Inverted index over purified content via SQLite FTS5. Exact keyword matching for names, dates, places.
Aho-Corasick entity extraction (<1ms) → 2-hop graph traversal → linked memories.
Activated by temporal intent in query ("when", "last week", month names). Time-windowed retrieval.
score(m) = Σ wi ⁄ (k + ranki)
A memory ranked #5 in vector AND #50 in BM25 can outrank one at #1 in vector alone. Weights adapt dynamically based on channel confidence. Cross-signal fusion yields 10–30% improvement over single-channel retrieval.
LLM-powered memory consolidation. Four phases transform raw episodes into structured knowledge.
Time-based importance decay applied to all existing memories. Memories below threshold auto-pruned.
importance -= decay_rate × days_since_accessLLM reads each episode independently and extracts atomic, self-contained facts with timestamps.
Extracted facts are reconciled against existing memories. The LLM proposes ADD / UPDATE / DELETE against integer-indexed IDs; without an LLM, deterministic cosine dedup applies.
No-LLM fallback: cosine distance < 0.15 → considered duplicate. Deterministic, no hallucination risk.
Single combined LLM call extracts entities and relationships. Aho-Corasick automaton links memories ↔ entities for spreading activation.
FSRS-inspired power-law decay. Memories fade, but access reinforces stability.
R(t, S) = (1 + t/(c·S))−p
S′ = S × (1 + g × (1 − R))
Accessed memories grow exponentially more stable.
score = sim × (0.7·R + 0.3·imp)
70% recency/stability, 30% tagged importance.
Rust workspace. Single SQLite file. No external infrastructure.
One Rust core, several ways to use it — each route labeled with its real status.
NAPI-RS binding for Electron and Node services.
npm install @wjmwjmwb/memme
const { MemoryStore } = require('@wjmwjmwb/memme');The core engine, used directly as a workspace crate.
use memme_core::{MemoryStore, AddOptions};
store.add("主人对花生严重过敏。", AddOptions::new("owner-001"))?;PyO3 + maturin. The PyPI 0.1.1 wheel is the legacy DuckDB build.
# From the repository root:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install maturin
maturin develop \
--manifest-path crates/memme-python/Cargo.toml \
--releaseThen configure the SQLite extension using the Python installation guide.
UniFFI bindings exist; VexDB-Lite mobile runtime wiring is still in progress.
cargo build -p memme-ffiwasm-bindgen crate exists, but is not yet wired to the VexDB-Lite SQLite runtime.
Axum server with Bearer auth, backups, and OpenAPI. Local ONNX embeddings by default.
POST /v1/events POST /v1/recall
POST /v1/backups GET /diagnoseModel Context Protocol stdio server for Codex Desktop, Cursor, Claude Desktop.
{
"command": "memme-mcp",
"args": ["--db-path", "memory.db"]
}Also configure MEMME_VEXDB_LITE_EXTENSION, OPENAI_API_KEY, EMBEDDING_URL, and LLM_URL in the client environment. Both URLs must be full API endpoints.
Defense in depth. From immutable records to privacy-aware exports — security is built into the engine, not bolted on.
Mark any memory as immutable. Once locked, it cannot be modified or deleted — guaranteed at the storage layer.
Public APIThree tiers: LocalOnly (never leaves device), Syncable, and EncryptedSync. Enforced on export and sync.
Public APISet per-memory TTL. Expired memories are automatically pruned during meditation — no manual cleanup needed.
Public APIEvery create, update, and delete is logged in the history table with timestamp, operation type, and before/after snapshot.
REST server supports optional API key authentication via Bearer token. Configurable per deployment.
Public APIConfigurable cross-origin policy on the REST server. Restrict access to trusted domains only.
Public APIConfigure LLM extraction to skip sensitive content categories. Tell the engine what not to remember.
Public APIAll queries use parameterized $N placeholders. Collection names validated against alphanumeric whitelist.
Content hash-based deduplication and integrity checking. Detect and prevent duplicate or corrupted entries.
InternalSubscribe to memory lifecycle events (create, update, delete) via configurable webhook endpoints. Feature-gated.
Public APIFrom atomic file backup to cross-platform conversation import. Your data, your control.
SQLite WAL checkpoint followed by atomic file copy. Consistent snapshot guaranteed even under concurrent writes.
Validates backup file integrity before restoring. Atomic swap — either fully restores or leaves the original untouched.
Continuous backup with configurable replica paths. On startup, automatically detects and recovers from the latest valid replica.
Complete data export as JSON: memories, events, episodes, entities, relationships, identity, sessions. Portable across deployments.
Incremental export based on version numbers. Only changed data since last sync — bandwidth-efficient for mobile and edge devices.
Lightweight memory-level export for sharing or migration. Includes embeddings, metadata, and entity links.
Import conversation history from ChatGPT, Claude, and Gemini. Auto-detects format and maps to MemMe events.
Exports automatically skip LocalOnly memories. Privacy levels are enforced at the export boundary, not just the API.
MemMe’s product benchmark. Scenarios cover owner safety, per-pet relationships, fresh events, privacy isolation, Chinese retrieval, expiration, correction, and deletion.
| Metric | 0.1.2 release |
|---|---|
| Required scenarios | 11 / 11 |
| Extended scenarios | 3 / 3 |
| Recall@10 | 100% |
| Search p50 | 1.999 ms |
| Search p95 | 3.062 ms |
| Search p99 | 17.128 ms |
| Write throughput | 445.7 memories/s |
| SQLite file size | 10.4 MB |
2,000 memories · median of three independent runs · deterministic local test embeddings · x86_64 process under Rosetta on Apple Silicon. These numbers validate the storage and retrieval contract — they do not prove final reply quality or production performance.