Local MemoryCAUTION
A lightweight, powerful local memory server for AI agents supporting text, entities, and relations. Enables persistent codebase understanding and user preference management.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
A local-first MCP server that gives AI agents shared, durable memory through hybrid semantic search, SQLite FTS5, and a knowledge graph—without Docker or a required cloud service.
Why use it?
- Shared across agents: one SQLite database can serve Codex, Claude,
desktop clients, IDE integrations, and custom MCP clients.
- Hybrid recall: when
sqlite-vecis available, local
all-MiniLM-L6-v2 embeddings and FTS5 keyword evidence are merged. FTS remains available as the explicit fallback.
- Temporal recall: search natural-language periods such as
last weekor
in 2025, or pass an explicit ISO startDate and endDate.
- Adaptive ranking: relevance, time-decayed importance, tags, and bounded
recent familiarity work together without rewriting importance on every recall.
- Auditable lifecycle: memories can be reinforced, marked outdated or
incorrect, restored, exported, or forgotten.
- Structured context: entities, relations, observations, conversations,
tasks, and todos live beside free-form memories.
- Local by default: memory data stays in your configured SQLite file.
Optional LLM features send input only to the OLLAMA_URL you configure.
For every option and tool, see the extended guide.
Requirements
- Node.js 22 or newer on a supported LTS release.
- Python and C++ build tools when
better-sqlite3has no matching prebuild. - Windows users can install Desktop development with C++ through Visual
Studio Build Tools.
Windows ARM64 semantic search is supported by a bundled, checksum-verified sqlite-vec v0.1.9 DLL. WSL2 remains a supported alternative.
Quick start
Add the published package to an MCP client:
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@beledarian/mcp-local-memory@2"],
"env": {
"ARCHIVIST_STRATEGY": "nlp"
}
}
}
}f7c706bf4498OBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add mcp-local-memory --env AUTH_TOKEN=${AUTH_TOKEN} --env MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN} -- npx -y @beledarian/[email protected]{
"mcpServers": {
"mcp-local-memory": {
"command": "npx",
"args": [
"-y",
"@beledarian/[email protected]"
],
"env": {
"AUTH_TOKEN": "${AUTH_TOKEN}",
"MCP_AUTH_TOKEN": "${MCP_AUTH_TOKEN}"
}
}
}
}Exposed tools (27)
14 read · 8 write · 5 destructive. Blast radius: 5 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
add_task | write | Add a task to the task list. Tasks can be scoped to a specific conversation or be global (null conversation_id). **Remember to remove outdated or completed tasks to prevent pollution.** |
add_todo | write | Create a new todo item. |
cli | read | Single entry point for all tools using a simplified command-line syntax. Saves tokens by replacing strict JSON schemas. commands: remember, recall, graph, todo, task, entity... |
cluster_memories | read | Cluster memories into topics. Useful for getting a high-level overview of what knowledge is stored. |
complete_todo | read | Mark a todo as completed. This moves it from the active list to long-term memory. |
consolidate_context | read | OPTIONAL: Extract important facts from a brief conversation summary. Agent provides 50-100 token summary of recent discussion. Tool extracts structured, novel facts using NLP or LLM. Use to catch memories the agent might have missed explicitly saving. |
create_entity | write | Define a structured entity (person, place, topic) in the knowledge graph. This helps link related facts together. |
create_relation | write | Create a directional relationship between two entities (e.g., |
delete_entity | destructive | Delete an entity and all its relations. Use this to remove incorrect or duplicate entities (like |
delete_observation | destructive | Delete specific observations from an entity. Use this to remove incorrect or outdated facts. |
delete_relation | destructive | Delete a relationship link between two entities. Use this to cleanup incorrect connections. |
delete_task | destructive | Delete a task from the task list. Use this to remove outdated or completed tasks to prevent clutter. |
export_memories | read | Back up all stored memories to a local JSON file. Useful for data portability or debugging. |
forget | destructive | Remove a specific memory using its ID. Use this if the user asks you to forget something or if the information is no longer accurate. |
init_conversation | read | Initialize a new conversation session with a unique ID. This allows for conversation-scoped task lists. Call this at the start of a conversation to generate a conversation ID. The returned payload is minimal; you MUST subsequent call |
list_recent_memories | read | Get the most recently added memories. Useful for seeing the |
list_tasks | read | List tasks, optionally filtered by conversation ID or status. Use this to view your current task checklist. |
list_todos | read | List current todo items. |
read_graph | read | Explore the knowledge graph. Use this to see how entities are connected or to get a summary of everything known about a specific entity. |
recall | read | Search active memories without changing lifecycle state, importance, reinforcement, or decay. Returned active results may record bounded hashed familiarity telemetry. Outdated and incorrect memories are suppressed unless include_outdated=true. Use reinforce_memory only after evaluating a result. |
reinforce_memory | read | Record explicit, auditable feedback after evaluating a memory. Outdated and incorrect memories are suppressed from default recall; restore makes one active again. Positive feedback has capped, diminishing gains. Do not call this merely because recall returned the memory. |
remember_fact | write | Save an important fact or piece of information to long-term memory. **USE THIS TOOL FREQUENTLY AND PROACTIVELY** whenever the user shares anything worth remembering for future sessions—preferences, projects, goals, decisions, context, etc. Don |
remember_facts | write | Save multiple distinct facts at once. Use this to batch saves and reduce latency. |
soul_maintenance | read | Maintains memory lifecycle importance using explicit reinforcement, bounded decay, and immune tags. Passive recall has no effect. |
test_tool | read | a test tool |
update_entity | write | Update an entity |
update_task_status | write | Update the status of a task. Use this to mark tasks as in-progress or complete. **Remove completed tasks when they |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (3 observation(s))
- Network
- declared (6 observation(s))
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (5)
vec0.dll
delete_entity, delete_observation, delete_relation, delete_task, forget
new URL('../../vendor/sqlite-vec/windows-arm64/vec0.dll', import.meta.url),const baseUrl = `http://127.0.0.1:${addr.port}`;@huggingface/transformers, @modelcontextprotocol/sdk, better-sqlite3, chrono-node, compromise, fs-extra, sqlite-vec, uuid
Gates applied: no_behavioural_pass.
f7c706bf4498full audit observations/trust-audit/mcp-server/beledarian__local-memory-2.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | f7c706bf4498 | CAUTION | B | 89 | first audit |
Questions
What is the Local Memory MCP server?
A lightweight, powerful local memory server for AI agents supporting text, entities, and relations. Enables persistent codebase understanding and user preference management.
What tools does Local Memory expose?
27 in total: 14 read-only, 8 that write, and 5 that can delete or overwrite (delete_entity, delete_observation, delete_relation, delete_task, forget). Every one is listed on this page with its risk.
Is Local Memory safe to connect to an agent?
With care. The audit graded it B (89/100) and found 5 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 5 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Local Memory need?
It reads AUTH_TOKEN and MCP_AUTH_TOKEN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Local Memory run?
It speaks sse, stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as @beledarian/mcp-local-memory at 2.1.1.
How current is this page?
The grade is for one exact copy of the source (f7c706bf4498), read on 2026-10-08. The repository is watched and re-audited when it changes.