{
  "markdown": "# Local Memory MCP Server\n\nA local-first MCP server that gives AI agents shared, durable memory through\nhybrid semantic search, SQLite FTS5, and a knowledge graph—without Docker or a\nrequired cloud service.\n\n![Local Memory MCP demo](docs/image.png)\n\n## Why use it?\n\n- **Shared across agents:** one SQLite database can serve Codex, Claude,\n  desktop clients, IDE integrations, and custom MCP clients.\n- **Hybrid recall:** when `sqlite-vec` is available, local\n  `all-MiniLM-L6-v2` embeddings and FTS5 keyword evidence are merged. FTS\n  remains available as the explicit fallback.\n- **Temporal recall:** search natural-language periods such as `last week` or\n  `in 2025`, or pass an explicit ISO `startDate` and `endDate`.\n- **Adaptive ranking:** relevance, time-decayed importance, tags, and bounded\n  recent familiarity work together without rewriting importance on every\n  recall.\n- **Auditable lifecycle:** memories can be reinforced, marked outdated or\n  incorrect, restored, exported, or forgotten.\n- **Structured context:** entities, relations, observations, conversations,\n  tasks, and todos live beside free-form memories.\n- **Local by default:** memory data stays in your configured SQLite file.\n  Optional LLM features send input only to the `OLLAMA_URL` you configure.\n\nFor every option and tool, see the\n[extended guide](docs/extended-guide.md).\n\n## Requirements\n\n- Node.js 22 or newer on a supported LTS release.\n- Python and C++ build tools when `better-sqlite3` has no matching prebuild.\n- Windows users can install **Desktop development with C++** through Visual\n  Studio Build Tools.\n\nWindows ARM64 semantic search is supported by a bundled, checksum-verified\n`sqlite-vec` v0.1.9 DLL. WSL2 remains a supported alternative.\n\n## Quick start\n\nAdd the published package to an MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@beledarian/mcp-local-memory@2\"],\n      \"env\": {\n        \"ARCHIVIST_STRATEGY\": \"nlp\"\n      }\n    }\n  }\n}\n```\n\nThe default database is `~/.memory/memory.db`. The first semantic recall may\ndownload the local embedding model.\n\nGlobal installation provides both `memory` and `mcp-local-memory`:\n\n```bash\nnpm install -g @beledarian/mcp-local-memory@2\nmemory --help\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/Beledarian/mcp-local-memory.git\ncd mcp-local-memory\nnpm install\nnpm run build\nnpm start\n```\n\nSee the [Codex + WSL2 setup](docs/extended-guide.md#codex--wsl2) when the\ndatabase or server runs inside Linux.\n\n## Remote Server & Docker Deployment (SSE)\n\n`mcp-local-memory` supports native **HTTP/SSE transport** for centralized setups across multiple workstations, laptops, Tailnets, or VPS instances:\n\n```bash\n# Run standalone SSE server on port 8320 with optional Bearer token auth:\nnode dist/index.js --transport sse --port 8320 --token \"your-secret-token\"\n\n# Or run via Docker Compose:\ndocker compose up -d\n```\n\nConfigure your remote MCP client (`mcp_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"url\": \"https://your-server.ts.net:8320/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-secret-token\"\n      }\n    }\n  }\n}\n```\n\n## Essential configuration\n\n| Variable | Default | Purpose |\n| :--- | :--- | :--- |\n| `MEMORY_DB_PATH` | `~/.memory/memory.db` | SQLite database location. |\n| `MCP_TRANSPORT` | `stdio` | `stdio` (default) or `sse` (remote HTTP/SSE server). |\n| `PORT` / `MCP_PORT` | `8320` | HTTP port when running in SSE mode. |\n| `MCP_AUTH_TOKEN` | unset | Optional Bearer token for remote SSE authentication. |\n| `ARCHIVIST_STRATEGY` | `nlp` | `passive`, `nlp`, `llm`, or a comma-separated combination. |\n| `OLLAMA_URL` | `http://localhost:11434/api/generate` | Optional LLM generation endpoint. |\n| `MEMORY_SEMANTIC_WEIGHT` | `0.9` | Retrieval relevance versus decayed importance. |\n| `MEMORY_MIN_RELEVANCE` | `0.55` | Minimum relevance required before a candidate can be returned. |\n| `MEMORY_RECALL_FAMILIARITY_MAX_BOOST` | `0.03` | Maximum temporary familiarity contribution; `0` disables future recording and scoring but does not purge existing rows. |\n| `MEMORY_RECALL_FAMILIARITY_WINDOW_DAYS` | `30` | Recent exposure window. |\n| `USE_WORKER` | `false` | Run archivist processing in a worker while retaining durable acknowledgement. |\n| `EXTENSIONS_PATH` | unset | Directory containing opt-in JavaScript extensions. |\n\nAll scoring, context, archivist, task, and extension variables are documented\nin the [configuration reference](docs/extended-guide.md#configuration).\n\n## How recall works\n\n`recall` supports both topical and temporal questions:\n\n- Semantic vector and FTS5 keyword candidates are retrieved independently and\n  merged, so an exact term is not hidden by a semantic result.\n- Natural-language dates such as `yesterday`, `last week`, and `in 2025` are\n  recognized in the query. ISO `startDate` and `endDate` filters are also\n  available.\n- Weak matches are omitted, near-duplicates are collapsed, and outdated or\n  incorrect memories stay hidden unless explicitly requested.\n- Relevant results are ranked using retrieval evidence, query coverage, tags,\n  time-decayed importance, and a small recent-familiarity signal.\n- Each returned active memory can record one familiarity exposure per\n  normalized-query hash and UTC day. The contribution is temporary and bounded\n  to `0.03` by default; it does not rewrite importance or refresh decay.\n\n`reinforce_memory` provides the stronger, durable feedback path:\n\n- `used` or `important` record positive evidence.\n- `irrelevant` lowers importance.\n- `incorrect` or `outdated` suppresses the memory without deleting history.\n- `restore` returns a suppressed memory to active recall.\n\nThe [extended scoring guide](docs/extended-guide.md#hybrid-recall-scoring)\ndocuments the formula, thresholds, deduplication, privacy limits, decay, and\nevery familiarity control.\n\n## Entities, relations, and the graph\n\nFree-form memories and structured knowledge complement each other:\n\n- **Entities** represent people, projects, places, topics, or other named\n  concepts. Each has a type, importance, and appendable observations.\n- **Relations** are directional triples such as\n  `Project A --[uses]--> SQLite`. Creating a relation also creates any missing\n  endpoint as an `Unknown` entity.\n- **Automatic extraction** can identify entities and relations while saving a\n  fact. Use `ARCHIVIST_STRATEGY=nlp` for local extraction, `llm` for the\n  configured Ollama endpoint, or `passive` for manual graph maintenance.\n- **Graph exploration** can return an overview or a centered one- or two-hop\n  neighborhood with entity observations, relations, and related memories.\n- **Graph maintenance** supports renaming or deleting entities, removing exact\n  observations, and deleting individual relations. Entity renames update\n  connected relations.\n- **Clustering** groups semantically related memories and entities into topic\n  overviews when embeddings are available.\n\nUse `recall` for ranked free-form retrieval and `read_graph` when connections\nbetween named concepts matter. They are complementary views of the same local\nknowledge base.\n\n## MCP surface\n\n| Area | Tools and resources |\n| :--- | :--- |\n| Memory | `remember_fact`, `remember_facts`, `recall`, `reinforce_memory`, `list_recent_memories`, `forget`, `export_memories` |\n| Graph | `create_entity`, `update_entity`, `delete_entity`, `create_relation`, `delete_relation`, `delete_observation`, `read_graph`, `cluster_memories` |\n| Conversations | `init_conversation`, `add_task`, `update_task_status`, `list_tasks`, `delete_task` |\n| Todos | `add_todo`, `complete_todo`, `list_todos` |\n| Optional extraction | `consolidate_context` when `ENABLE_CONSOLIDATE_TOOL=true` |\n| Resources | `memory://current-context`, `memory://turn-context`, task and todo resources |\n\nSee the [complete tool reference](docs/extended-guide.md#tools-for-agents) for\narguments and lifecycle behavior.\n\n## Upgrading safely\n\nWhen upgrading from 1.x:\n\n- move to Node.js 22;\n- back up `MEMORY_DB_PATH`;\n- expect automatic additive schema migration;\n- note that `MEMORY_SEMANTIC_WEIGHT` now means relevance versus importance;\n- recall no longer raises importance or refreshes decay;\n- run importance normalization only if you want to reset historical passive\n  popularity.\n\nThe project does not claim crash-proof, zero-loss migration under every\ninterruption scenario, so a verified backup remains the safety boundary.\n\nOlder releases passively increased `importance` and `access_count` during\nrecall. Preview normalization before changing anything:\n\n```bash\nnpm run normalize:importance -- --db ~/.memory/memory.db\n```\n\nApplying normalization is optional and requires an explicit, non-existing\nbackup path. See the\n[migration and normalization guide](docs/extended-guide.md#one-time-importance-normalization).\n\n## Documentation\n\n- [Extended installation, configuration, and operations](docs/extended-guide.md)\n- [Short agent instructions](docs/example_instructions.md)\n- [Comprehensive agent prompt](docs/detailed_prompt.md)\n- [Changelog](CHANGELOG.md)\n- [Test and smoke-probe guide](tests/README.md)\n- [Windows ARM64 sqlite-vec provenance](vendor/sqlite-vec/README.md)\n\n## Development\n\nThese commands require a source checkout:\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n`npm test` covers scoring, schema migration, lifecycle and familiarity,\nprivacy/provenance, MCP contracts, packaging, and native vector or FTS fallback.\n\n## License\n\nMIT\n",
  "bytes": 9478,
  "sha": "46ecb2b318c49dd83047f37da0155c04c59e6372529122732188d43e62c68c4a",
  "repo_slug": "beledarian/mcp-local-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_beledarian_mcp_local_memory_404a315a/readme"
}