Memento provides persistent memory capabilities through a SQLite/PostgreSQL-based knowledge graph with semantic search using BGE-M3 embeddings for intelligent context retrieval across conversations.
Core Operations:
Entity Management: Create, read, and delete entities with types, importance levels (critical/important/normal/temporary/deprecated), and tags for categorization
Observations: Add and delete text observations attached to entities, automatically indexed for full-text and semantic search
Relationships: Create and delete directed relations between entities with typed connections
Search and Retrieval:
Hybrid Search: Query using keyword matching, semantic similarity, or combined approaches with configurable distance thresholds and result limits
Graph Navigation: Retrieve entire knowledge graphs or expand specific entities to view all observations and relations
Enhanced Relevance: Scoring system incorporating temporal, popularity, contextual, and importance factors
Key Features:
Offline Operation: Fully offline quantized BGE-M3 model (1024-dimensional embeddings) without external API calls
Multiple Backends: Support for SQLite (FTS5) and PostgreSQL with vector extension capabilities
Cascading Deletion: Remove entities with automatic cleanup of linked observations and relations
MCP Integration: Designed for seamless integration with Claude Desktop via MCP protocol
Leverages Node.js for running the embedding model offline via @xenova/transformers, enabling semantic search capabilities without requiring an internet connection.
Provides a persistent memory storage backend using SQLite with FTS5 for fast keyword search and sqlite-vec for semantic vector search, supporting a structured graph of entities, observations, and relations.
Memento
Some memories are best persisted.
Provides persistent memory capabilities through a SQLite-based knowledge graph that stores entities, observations, and relationships with semantic search using BGE-M3 embeddings for intelligent context retrieval across conversations.
Features
Semantic vector search (sqlite-vec/pgvector, 1024d)
Offline embedding model (
bge-m3)Modular repository layer with SQLite and PostgreSQL backends
Enhanced Relevance Scoring with temporal, popularity, contextual, and importance factors
Structured graph of
entities,observations, andrelationsEasy integration with Claude Desktop (via MCP)
Related MCP server: MCP Memory LibSQL
Prerequisites
System SQLite Version Check
Memento requires SQLite 3.38+. Most macOS and Linux distros ship sqlite3 out of the box, but double-check that it's there and new enough:
Important Note: This check is just to verify SQLite is installed on your system. Memento does NOT use the sqlite3 CLI for its operation it uses the Node.js sqlite3 module internally.
If you see "command not found" (or your version is older than 3.38), install SQLite:
Platform | Install command |
macOS (Homebrew) |
|
Debian / Ubuntu |
|
Configuration
Memento now supports pluggable storage backends. Configuration is controlled entirely through environment variables so it remains easy to embed inside MCP workflows.
Variable | Description |
| Optional selector for the database backend. Defaults to
. Set to
to enable the PostgreSQL manager. |
| Filesystem path for the SQLite database file (only used when the driver is
). |
| Optional absolute path to a pre-built
extension shared library. |
/
| PostgreSQL connection string consumed by the
client. |
,
,
,
,
| Individual PostgreSQL connection parameters. Used when no DSN is provided. |
| When set to
, SSL will be enabled with
. |
PostgreSQL notes
The PostgreSQL manager requires the
pgvectorextension. It is automatically initialized withCREATE EXTENSION IF NOT EXISTS vector.
Claude Desktop:
Troubleshooting
sqlite-vec Extension Issues
Important: Memento loads the sqlite-vec extension programmatically through Node.js, NOT through the sqlite3 CLI.
Common misconceptions:
❌ Creating shell aliases for sqlite3 CLI won't affect Memento
❌ Loading extensions in sqlite3 CLI won't help Memento
✅ Use the npm-installed sqlite-vec or set
SQLITE_VEC_PATHenvironment variable if automatic detection fails. This should point to the Node.js-compatible version of the extension, typically found in yournode_modulesdirectory.
If automatic vec loading fails:
API Overview
This server exposes the following MCP tools:
create_entitiescreate_relationsadd_observationsdelete_entitiesdelete_relationsdelete_observationsread_graphsearch_nodesopen_nodesset_importance- Set importance level (critical/important/normal/temporary/deprecated)
An example of an instruction set that an LLM should know for effective memory handling (see MEMORY_PROTOCOL.md)
Embedding Model
This project uses @xenova/transformers, with a quantized version of bge-m3, running fully offline in Node.js.
License
MIT