OneMemory – self-hosted shared memory for AI agents over MCP

Developer calasdan-sketch launched OneMemory, a self-hosted shared memory store connecting artificial intelligence agents across desktop, web, and mobile environments over the Model Context Protocol and REST APIs. According to github.com's report, the software links tools including Claude Code, Cursor, Copilot, Cline, Continue, and n8n to a common SQLite database. Distributed under the MIT license, OneMemory operates as a single Node.js process using native SQLite features rather than external vector databases.

This report details the runtime architecture, multi-agent synchronization mechanics, network routing, and security protections introduced in OneMemory. It is tailored for software engineers and systems operators seeking cross-client state persistence without deploying heavy infrastructure. Sections below outline Node 24 runtime prerequisites, dual-port networking, write-time secret scanning, prompt-injection quarantine, and Git-compatible Markdown backups.

OneMemory – self-hosted shared memory for AI: what actually changed

The release packages a complete persistence architecture into a single Node.js runtime, omitting standalone vector databases, external servers, and Python runtime dependencies. OneMemory relies directly on two runtime packages, @modelcontextprotocol/sdk and zod, totaling roughly 94 packages when including underlying protocol dependencies. The engine strictly requires Node.js 24 or newer to access the standard library node:sqlite module, which is absent from Node 22 and earlier. Environments unable to upgrade their local Node runtime can deploy using the official Docker container via Docker Compose.

Persistent data resides outside the application package in ~/.onememory on Unix platforms and %USERPROFILE%\.onememory on Windows, ensuring npm updates never touch active databases. Directories receive owner-only permissions of 0700 while individual files default to 0600 on Linux and macOS. Network operations run across two ports: port 8790 hosts the administrative dashboard and REST endpoints, while port 8791 exposes MCP-over-HTTP bound to 127.0.0.1. Connecting remote agents requires placing an authenticated tunnel such as Tailscale or Cloudflare Tunnel in front of port 8791.

OneMemory – self-hosted shared memory for AI: how it works

Agents communicate with OneMemory through stdio streams or HTTP requests using scoped bearer tokens enforcing read, write, or administrative permissions. Every incoming write command passes through an integrated memory linter before the server commits records to SQLite. The linter actively blocks API keys, JSON Web Tokens, private cryptographic keys, and high-entropy secrets. Concurrently, it detects prompt-injection instructions like directives to ignore previous instructions. Flagged injection attempts are quarantined for administrator inspection, remaining hidden from search and recall queries until explicitly approved.

Cross-session updates run on a local change feed accessed via memory_since or GET /changes. Rather than constantly polling, clients initiate a long-polling live wait by requesting wait=25, which pauses the HTTP response until data changes occur. While the server permits wait times up to 55 seconds, 25 seconds is recommended because proxies and tunnels often terminate idle connections at 30 seconds. The server limits live waits to 16 concurrent requests per token, freeing slots automatically upon unexpected client disconnection or server shutdown.

OneMemory – self-hosted shared memory for AI: why it matters now

Developers operating multiple artificial intelligence tools routinely encounter fragmented memory silos, requiring engineers to repeatedly restate infrastructure details across separate chats. OneMemory resolves this problem by offering a unified, locally hosted store accessible to any client supporting HTTP or the Model Context Protocol. Furthermore, multi-agent pipelines that aggregate untrusted external content risk spreading malicious instructions. By filtering writes through an inline memory linter before persisting data to disk, the architecture prevents prompt-injection attacks from poisoning recall workflows and blocks exposed secrets from leaking.

The architecture eliminates vector infrastructure overhead by pairing native SQLite storage with optional semantic retrieval through external Ollama or OpenAI-compatible embedding endpoints. The system supports natural-language time filters like yesterday evening, staleness warnings, and near-duplicate consolidation. For multi-machine collaboration, a Markdown synchronization engine exports individual notes with YAML front-matter into git-friendly directories. Distributed teams can synchronize these folders across computers using Git or Syncthing. When concurrent edits occur, a three-way merge algorithm applies newer modifications while preserving conflicting versions to prevent data loss.

OneMemory – self-hosted shared memory for AI: who is affected

Software engineers operating command-line coding tools and web assistants face streamlined onboarding when integrating OneMemory. Claude Code users connect the system using claude mcp add onememory -- onememory mcp, or execute it dynamically via npx without global installations. Developers using Claude Desktop, Cursor, and Copilot configure client connections by running onememory init to display configuration blocks. External applications like n8n can issue standard curl requests against port 8790 using Bearer tokens. Scoped token permissions ensure mobile devices assigned read-only tokens cannot accidentally wipe or corrupt stored memories.

System administrators gain centralized commands to monitor installations, manage storage paths, and orchestrate upgrades across client machines. Running onememory doctor inspects active Node versions, database locations, and authorization tokens to surface setup errors before deployment. Operators can redirect data paths away from default home directories using ONEMEMORY_HOME and ONEMEMORY_DB_PATH environment variables. When evaluating multi-agent architectures, administrators can benchmark OneMemory against alternative projects highlighted in its documentation, including mcp-memory-service, Basic Memory, OpenMemory, and the official Model Context Protocol reference server, comparing their dependency footprints.

OneMemory – self-hosted shared memory for AI: what to watch

Operators deploying OneMemory must implement reliable backup routines and separate cryptographic keys to maintain recovery readiness. Running onememory backup executes a live SQLite VACUUM INTO command, generating a consistent database copy without halting running servers. When at-rest encryption is active, the utility also backs up the local key file, requiring administrators to store the key separately from database archives. Backups export current note states rather than full revision histories, tracking revision counters without storing historical snapshots. The change feed prunes edit titles after 90 days.

System restoration introduces specific operational constraints that administrators should account for during recovery. Streaming JSON exports process notes in 500-item pages to cap memory usage, but importing archives into populated stores creates duplicate notes because the import API does not deduplicate records. Ingesting backups exceeding 200 notes defers rebuilding the similarity graph, requiring administrators to execute onememory rebuild-edges manually to restore neighbor ranking. Additionally, the memory linter uses pattern matching rather than published false-positive benchmarks, producing occasional false alarms on code alongside potential misses on novel injections.