Omni Memory MCP

Universal memory MCP server for multi-agent workflows.
100% local with SQLite + FTS5.

npm Package

• Package: @sharkdyt/omni-memory-mcp
• npm: https://www.npmjs.com/package/@sharkdyt/omni-memory-mcp
• Current latest: 1.0.7

Release Notes

v1.0.7

• Ships memory_context_pack for read-only, token-budgeted prompt assembly.
• Returns compact excerpts plus structured metadata without mutating access_count.
• Keeps the current local SQLite + FTS5 architecture: no schema migration, vector retrieval, or ranking rewrite.

Project Memory

This project does not keep local memory-bank/ files. Operational context is stored through Omni Memory itself.

Why this exists

• Keep AI memory local (no cloud dependency)
• Reuse the same memory across tools/agents
• Search fast with SQLite FTS5

Features

• Local-first storage (SQLite)
• Full-text search with FTS5
• MCP-native tools
• Progressive Disclosure: Searches return metadata and summaries instead of full text to prevent LLM context overflow.
• Context Packs: memory_context_pack assembles compact, token-budgeted excerpts for prompt construction.
• Active Forgetting Tracking: Read actions (memory_get) increment access_count and update accessed_at.
• CRUD operations (memory_add, memory_upsert, memory_get, memory_update, memory_delete, memory_list, memory_search)
• Context optimization tools (memory_prune)
• Diagnostic tools (memory_stats)
• Organization by area, project, and tags
• Shared long-term memory across multiple projects and multiple coding agents/clients
• Canonical MCP config + client adapters (OpenCode, Codex, Cursor)

Cross-Client MCP Standard

This project keeps one canonical MCP config and generates client-specific files.

Canonical source:

• config/mcp/servers.json

Generate adapters:

npm run mcp:generate

Validate adapters:

npm run mcp:validate

Generated files:

• config/mcp/generated/opencode.windows.json
• config/mcp/generated/opencode.posix.json
• config/mcp/generated/opencode.windows.array.npx.json
• config/mcp/generated/opencode.windows.string-args.npx.json
• config/mcp/generated/opencode.windows.array.fallback-dist.json
• config/mcp/generated/opencode.posix.array.npx.json
• config/mcp/generated/opencode.posix.string-args.npx.json
• config/mcp/generated/opencode.posix.array.fallback-dist.json
• config/mcp/generated/codex.windows.json
• config/mcp/generated/codex.posix.json
• config/mcp/generated/cursor.windows.json
• config/mcp/generated/cursor.posix.json

Compatibility matrix:

• docs/mcp-compatibility-matrix.md

Quick Start (Most Newbie Friendly)

If your MCP client supports command + args + env, use:

{
  "mcpServers": {
    "omni-memory": {
      "command": "npx",
      "args": ["-y", "@sharkdyt/omni-memory-mcp"],
      "env": {
        "OMNI_MEMORY_DIR": "~/.omni-memory"
      }
    }
  }
}

This is the easiest setup because:

• No manual clone path
• No manual build path
• Works after npm registry publish

OpenCode compatibility profiles

OpenCode support can vary by client version and environment.
This repository now generates three OpenCode profiles for each platform:

• array.npx: command as array (["npx","-y","@sharkdyt/omni-memory-mcp"])
• string-args.npx: command as string + args
• array.fallback-dist: shell command that tries npx and falls back to local dist/index.js

Recommended default for OpenCode:

• config/mcp/generated/opencode.<platform>.json (this points to array.fallback-dist)

If you prefer explicit profile selection, copy one of:

• config/mcp/generated/opencode.<platform>.array.npx.json
• config/mcp/generated/opencode.<platform>.string-args.npx.json
• config/mcp/generated/opencode.<platform>.array.fallback-dist.json

Path Guide (Relative vs Absolute)

If you prefer running from local source (dist/index.js), use an absolute path.

• Relative path example (can break): ./dist/index.js
• Absolute path example (recommended): full path to file on disk

Why relative paths break:

• Many MCP clients resolve paths from their own process working directory, not from your config file directory.

Absolute path examples

Linux:

{
  "command": "node",
  "args": ["/home/your-user/.local/mcp/omni-memory-mcp/dist/index.js"]
}

macOS:

{
  "command": "node",
  "args": ["/Users/your-user/.local/mcp/omni-memory-mcp/dist/index.js"]
}

Windows:

{
  "command": "node",
  "args": ["C:\\Users\\your-user\\.local\\mcp\\omni-memory-mcp\\dist\\index.js"]
}

Note:

• ~ is convenient, but not every client expands it consistently on Windows. Absolute paths are safer.

Install from Source (Local Dev)

git clone https://github.com/allanschramm/omni-memory-mcp.git
cd omni-memory-mcp
npm install
npm run build

Then configure your MCP client with node + absolute path to dist/index.js.

OpenCode / Codex / Cursor

Instead of writing each config by hand, generate client-specific adapters:

npm run mcp:generate

Then copy the generated file for your client/platform from config/mcp/generated/.

OpenCode troubleshooting priority

1. Use opencode.<platform>.json first (default fallback profile).
2. If your OpenCode build prefers native npx only, try opencode.<platform>.array.npx.json.
3. If your OpenCode build requires command string + args, use opencode.<platform>.string-args.npx.json.

Tools

memory_add

{
  "name": "User typescript preferences",
  "content": "User prefers TypeScript with strict mode",
  "area": "preferences",
  "project": "my-project",
  "tags": ["typescript", "coding-style"],
  "metadata": {
    "source": "conversation setup"
  }
}

Use memory_add for clearly new, one-off memories.

memory_upsert

{
  "name": "User typescript preferences",
  "content": "User prefers TypeScript with strict mode",
  "project": "my-project",
  "tags": ["typescript", "coding-style"],
  "allow_create": true
}

Note: memory_upsert is intentionally conservative. It uses normalized name + project matching, updates only when there is one clear candidate, and refuses to write when the match is ambiguous. Use memory_upsert before memory_add for durable facts, preferences, and evolving project memory.

memory_get

Note: Fetching a memory via memory_get registers an access (increments access_count and updates accessed_at), indicating the memory is actively used.

{
  "id": "abc123"
}

memory_update

{
  "id": "abc123",
  "name": "Updated typescript preferences",
  "content": "Updated content",
  "project": null,
  "metadata": null,
  "tags": ["new-tag"]
}

Use null for project or metadata to clear those values.

memory_delete

{
  "id": "abc123"
}

memory_list

Note: Enforces Progressive Disclosure. It returns only IDs, Names, and metadata. You must call memory_get with the specific ID to read the full content.

{
  "area": "snippets",
  "project": "my-project",
  "tag": "important",
  "limit": 20
}

memory_search

Note: Enforces Progressive Disclosure. It returns only IDs, Names, and metadata. You must call memory_get with the specific ID to read the full content.

{
  "query": "typescript configuration",
  "project": "my-project",
  "limit": 10,
  "enableAdvancedSyntax": false,
  "search_mode": "balanced"
}

Note: enableAdvancedSyntax allows FTS5 boolean logic (e.g. "typescript" AND "react" NOT "vue") but requires a strictly valid FTS5 query or it will throw an error. Note: search_mode tunes ranking only. balanced is the default, exact boosts exact title matches harder, and broad is more permissive for content-heavy results. Search results include a compact Match: explanation showing which indexed fields contributed to the result.

memory_context_pack

Note: Builds a compact prompt-ready bundle from matching memories without incrementing access_count. It keeps progressive disclosure intact by returning short excerpts instead of full documents.

{
  "query": "typescript configuration",
  "project": "my-project",
  "tag": "important",
  "max_tokens": 1200,
  "max_memories": 5,
  "search_mode": "balanced"
}

Returns:

• compact text for immediate agent use
• structured metadata with count, estimated_tokens, truncated, and per-memory excerpts
• excerpts ordered by the existing memory_search ranking

memory_stats

{}

Returns total memories, size on disk, breakdown by project and area, plus local upsert metrics such as memory_upsert_created and memory_upsert_updated.

memory_prune

Note: Cleans up memories that have decayed below a specific score dynamically calculated based on created_at, accessed_at, and access_count.

{
  "threshold_score": 0,
  "dry_run": true
}

Always use dry_run: true first to see how many and which memories would be pruned before running the destructible cleanup.

Memory Areas

| Area | Description | | --- | --- | | general | General notes | | snippets | Code snippets and patterns | | solutions | Problem-solution pairs | | preferences | User/team preferences |

Data Storage

Default directory:

~/.omni-memory/
|- omni-memory.db
|- omni-memory.db-wal
`- omni-memory.db-shm

Environment variables:

| Variable | Default | Description | | --- | --- | --- | | OMNI_MEMORY_DIR | ~/.omni-memory | Data storage directory | | OMNI_MEMORY_DB | {OMNI_MEMORY_DIR}/omni-memory.db | SQLite DB file path |

Development

npm install
npm run check
npm run build
npm test

Extra commands:

npm run dev    # watch mode
npm run start  # run server from dist/

Documentation and Memory Hygiene

For every meaningful project change, keep both sources of truth updated:

1. Repository docs (README.md, docs/*, compatibility/config docs) must reflect current behavior.
2. Omni Memory must receive a concise project memory entry with:
   • what changed,
   • why it changed,
   • constraints/assumptions,
   • next steps (if any).

Minimum release/update gate:

1. npm run mcp:generate
2. npm run mcp:validate
3. npm run check
4. Update docs for any behavior/config change
5. Add/update important project memory in Omni Memory

Post-change runtime verification for this repository:

6. npm run build
7. Sync repo dist/ into C:\Users\allan\.local\mcp\omni-memory-mcp\dist
8. Smoke test the deployed omni-memory-mcp

Operational checklist:

• docs/release-checklist.md

License

Apache 2.0. See LICENSE.