memocean-mcp — Local-first AI Memory MCP Server

A local MCP server for AI agents to search and manage knowledge stored in Obsidian vaults. Built for CJK (Chinese/Japanese/Korean) developers — 94.4% Hit@5 on Chinese queries with zero AI components required.

Core features:

• BM25/INSTR hybrid search — CJK-optimized, pure SQLite, no embeddings needed

• CLSC sonar compression — 92.5% token reduction (13x compression) on Obsidian notes

• Temporal knowledge graph — entity-relationship store with non-destructive invalidation

• Cross-agent memory sharing — multiple agents share one memory.db

• FATQ task queue — File-Atomic Task Queue for agent coordination

Quick Start

pip install memocean-mcp

Add to Claude Desktop / Claude Code .mcp.json:

{
  "mcpServers": {
    "memocean": {
      "command": "memocean-mcp",
      "env": {
        "MEMOCEAN_VAULT_ROOT": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Or register with Claude Code CLI:

MEMOCEAN_VAULT_ROOT=/path/to/vault claude mcp add memocean memocean-mcp

Related MCP server: obsidian-hybrid-search

Environment Variables

Backward-compat: CHANNELLAB_BOTS_ROOT → MEMOCEAN_DATA_DIR, CHANNELLAB_OCEAN_VAULT_ROOT → MEMOCEAN_VAULT_ROOT.

Available Tools

File-ingest dependency note

memocean_ingest_file depends on the PDF, DOCX, and PPTX extras from MarkItDown. They are pinned in pyproject.toml; install the project dependencies (for example, pip install .) rather than installing bare markitdown, which omits the PDF and DOCX converters.

Production deployment and drift guard

This host intentionally uses a normal package install, not an editable install. Changing memocean_mcp/ in this repository therefore does not change the code imported from user site-packages. This separation prevents an uncommitted worktree from silently becoming production behaviour.

After a reviewed memocean-mcp change is merged, an authorized production runner must use the single operator-facing deployment entry:

MEMOCEAN_PIP_BREAK_SYSTEM_PACKAGES=1 \
  /home/oldrabbit/.claude-bots/shared/bin/memocean-deploy.sh

The deploy command refuses dirty package sources, performs a non-editable, idempotent reinstall, runs the canonical content drift gate, and atomically records the deployed repository commit in logs/memocean-mcp-deployment.json. The deployment is successful only when the final check reports OK. ops/deploy.sh remains the package-local implementation used by the canonical entry and isolated fixture; it is not the operator runbook entry.

Debian marks its base interpreter as externally managed (PEP 668), so pip also requires the explicit MEMOCEAN_PIP_BREAK_SYSTEM_PACKAGES=1 opt-in shown above. The script applies pip's --break-system-packages only to the existing --user install path; target-directory installs do not receive it. This does not write into Debian's system package directory, but a user-site package can still shadow a distro package for this account. Use this opt-in only on the reviewed production host and interpreter. A dedicated virtual environment would avoid that override, but adopting one also requires moving the service runtime and is therefore a separate migration.

After review, install or refresh the recurring drift check with:

bash ops/install-drift-cron.sh

The installer creates one marked cron entry. The guard runs daily at 04:15 Asia/Taipei and appends a timestamped trigger=cron result to /home/oldrabbit/.claude-bots/logs/memocean-mcp-drift.log. Immediately after installation, run the check once with MEMOCEAN_DRIFT_TRIGGER=cron to verify the cron-path output format, then retain the crontab entry and a fresh scheduler-produced trigger=cron log line after the next scheduled run as activation evidence. The manual run and crontab entry alone do not prove that the scheduler is alive.

ops/check-deploy-drift.sh is a compatibility shim for the already deployed daily cron; it delegates to shared/bin/memocean-drift-check.sh, the same canonical gate used by deploy and the FATQ live probe. When drift exists, the guard also uses the existing mm_post path to notify Anya's Mattermost channel. An unchanged drift signature is sent once across consecutive daily runs; a changed signature is sent again, and a clean run resets the deduplication state. Notification failure is printed explicitly and never changes the drift result from exit 1. Host activation evidence must include an injected-drift message that was actually received, not only script configuration or a log line.

The drift guard compares only .py source files. It deliberately ignores __pycache__, .pyc, build metadata, and generated bytecode. A missing, extra, or changed .py file is listed and makes the command exit nonzero.

Search Architecture

Two-path retrieval, zero AI dependency by default:

CJK query  →  SQLite INSTR on radar.clsc  →  ranked by match_count
EN query   →  FTS5 BM25                   →  fallback to INSTR on miss

Benchmark (pure BM25/INSTR, no AI):

CLSC Sonar Compression

CLSC (Closet Lossy Summary for Chinese) extracts each document into a compact single-line sonar entry. Format:

[SLUG|ENTITIES|topics|"key_quote"|WEIGHT|EMOTIONS|FLAGS]

Compression ratio: 1,716,211 raw tokens → 129,529 sonar tokens = 13x (92.5% reduction).

Requirements

• Python 3.11+

• SQLite 3.35+

• Optional: markitdown[all] for file ingestion

• Optional: anthropic package for AI-assisted features (query expansion, reranking)

License

MIT — see LICENSE.

Acknowledgements

Built on MemPalace (dual-layer architecture, AAAK skeleton format) and inspired by GBrain (Compiled Truth + Dream Cycle design).