OPC Memory 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:

1. OPC project - The memory scripts and PostgreSQL database schema from the OPC repository
2. PostgreSQL database - Running with the OPC schema (sessions, file_claims, archival_memory tables)
3. 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)
"