OPC Memory MCP Server

MCP server that exposes OPC memory scripts as tools for Claude Code and Claude Desktop.

This project provides an MCP interface to the OPC (Opinionated Persistent Context) memory system from the OPC project. OPC enables semantic memory storage and retrieval, allowing Claude to learn from past sessions and maintain context across conversations.

Note: This server was originally built against Continuous-Claude-v3. As of v0.7.2, it targets the standalone OPC repository which contains the memory scripts, database schema, and pattern detection infrastructure.

Tools

| Tool | Description | |------|-------------| | store_learning | Store session learnings with embeddings for semantic recall | | recall_learnings | Semantic search over stored learnings | | query_documents | Scoped semantic search over ingested document collections (RAG) | | list_document_collections | List document collections and ingest stats | | scan_document_collection | Ingest one collection or all (admin/ingest) | | create_document_collection | Register a new document collection (admin/ingest) | | query_artifacts | Search Context Graph for precedent from past sessions | | index_artifacts | Index handoffs, plans, and continuity ledgers | | mark_handoff | Mark handoff outcomes for tracking | | start_daemon | Start the memory extraction daemon | | stop_daemon | Stop the memory extraction daemon | | daemon_status | Check daemon status and view recent logs | | detect_patterns | Run on-demand pattern detection across stored learnings |

Prerequisites

This MCP server requires:

OPC project - The memory scripts and PostgreSQL database schema from the OPC repository
PostgreSQL database - Running with the OPC schema (sessions, file_claims, archival_memory tables)
Environment variables - DATABASE_URL pointing to your PostgreSQL instance

See the OPC repository for setup instructions.

OPC Directory Configuration

The OPC directory path can be configured in two ways (in priority order):

1. Environment Variable (Override)

export CLAUDE_OPC_DIR="/path/to/your/opc"

Use this for temporary overrides or CI/CD environments.

2. Config File (Persistent)

Create ~/.claude/opc.json:

{
  "opc_dir": "/path/to/your/opc"
}

This is the recommended approach for persistent user configuration.

Resolution Order

Hooks and scripts resolve OPC_DIR in this order:

| Priority | Source | Use Case | |----------|--------|----------| | 1 | CLAUDE_OPC_DIR env var | Explicit override, CI/CD | | 2 | ~/.claude/opc.json | Persistent user preference | | 3 | ${CLAUDE_PROJECT_DIR}/opc | Project-local setup | | 4 | ~/.claude | Global installation |

Hook Integration

If you're building hooks that need to reference OPC infrastructure, use the shared opc-path.ts module. See the examples/hooks/ directory for a complete example you can copy to your ~/.claude/hooks/src/shared/ directory.

MCP Server Resolution

The main.py MCP server uses the same resolution logic:

def get_opc_dir() -> str:
    # 1. CLAUDE_OPC_DIR env var
    # 2. ~/.claude/opc.json config file
    # 3. Fallback default

This means the MCP server will automatically use your configured OPC path.

Note on Skills

If you have Claude Code skills that reference OPC memory tools (e.g., /recall, /remember), you may need to update them to use the MCP tool names:

| Skill Reference | MCP Tool Name | |-----------------|---------------| | store_learning | mcp__opc-memory__store_learning | | recall_learnings | mcp__opc-memory__recall_learnings | | query_artifacts | mcp__opc-memory__query_artifacts | | index_artifacts | mcp__opc-memory__index_artifacts | | mark_handoff | mcp__opc-memory__mark_handoff | | start_daemon | mcp__opc-memory__start_daemon | | stop_daemon | mcp__opc-memory__stop_daemon | | daemon_status | mcp__opc-memory__daemon_status | | detect_patterns | mcp__opc-memory__detect_patterns |

Installation

cd /Users/stephenfeather/Tools/opc-memory-mcp
uv sync

Usage

Run directly

uv run opc-memory-server

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "opc-memory": {
      "command": "uv",
      "args": ["--directory", "/Users/stephenfeather/Tools/opc-memory-mcp", "run", "opc-memory-server"]
    }
  }
}

Claude Code Configuration

Add to .claude/settings.json or global settings:

{
  "mcpServers": {
    "opc-memory": {
      "command": "uv",
      "args": ["--directory", "/Users/stephenfeather/Tools/opc-memory-mcp", "run", "opc-memory-server"]
    }
  }
}

Tool Examples

store_learning

Store a learning about hook development patterns.

Parameters:
- content: "TypeScript hooks require npm install before they work"
- learning_type: "WORKING_SOLUTION"
- context: "hook development"
- tags: "hooks,typescript"
- confidence: "high"

recall_learnings

Search for past learnings about authentication.

Parameters:
- query: "authentication patterns"
- k: 5
- text_only: false (use embeddings)

Observability: MCP recalls are logged to the OPC recall_log table with source = "mcp" (since v0.7.5), distinguishing them from hook- and cli-driven recalls for cross-project mis-scope analysis.

query_documents

Scoped RAG search over ingested document collections (wraps opc-docs query).

Search the documents for a topic.

Parameters:
- text: "what does the contract say about termination"
- collection: "" (default; searches global-scope collections only)
- limit: 8 (max 100)

Scope is a security boundary: the default search is global-only. A restricted collection (e.g. medical/legal docs) surfaces only when its name is passed via collection. There is no "all scopes" option — pass a collection name solely when the caller explicitly targets it. The companion list_document_collections is read-only; scan_document_collection and create_document_collection are admin/ingest operations.

index_artifacts

Index all artifacts:
- mode: "all"

Index specific file:
- mode: "file"
- file_path: "/path/to/handoff.md"

mark_handoff

Mark the latest handoff as successful:
- outcome: "SUCCEEDED"
- notes: "All tasks completed"

detect_patterns

Dry run to preview patterns:
- dry_run: true

Run detection and write to database:
- min_confidence: 0.3
- use_llm: false

View last run's report:
- report: true

Daemon Management

Check daemon status:
daemon_status()
# Returns: running status, PID, recent log entries

Start the daemon:
start_daemon()
# Starts memory extraction daemon if not running

Stop the daemon:
stop_daemon()
# Stops the running daemon

Development

Test the server:

# Check it starts without errors
uv run opc-memory-server &
PID=$!
sleep 2
kill $PID

# Test individual tools via subprocess
uv run python -c "
from main import store_learning, recall_learnings
result = recall_learnings(query='test', k=1)
print(result)
"

OPC Memory MCP Server