@sem/mcp-server

Coherent Memory for LLM Agents

A memory layer that detects contradictions and surfaces them for review. Unlike append-only logs or RAG retrieval, this system models beliefs as nodes in a constraint network where semantic similarity implies expected agreement.

What it does

When you store beliefs, the system:

1. Embeds them locally (Xenova/all-MiniLM-L6-v2, no API calls)
2. Auto-links to similar existing beliefs
3. Computes strain using hybrid geometric-logical energy
4. Surfaces contradictions when beliefs conflict

Installation

# Install globally
npm install -g @sem/mcp-server

# Or run via npx
npx @sem/mcp-server

Claude Code / MCP Configuration

Add to your mcp_servers.json:

{
  "mcpServers": {
    "sem-memory": {
      "command": "npx",
      "args": ["@sem/mcp-server"],
      "env": {
        "SEM_DATA_DIR": "/path/to/your/memory"
      }
    }
  }
}

Tools

memory_add

Add a belief to memory.

memory_add({
  belief: "The user prefers dark mode",
  source: "settings conversation",
  confidence: 0.9
})
// Returns: { id, autoLinked, contradictions }

memory_query

Search for relevant beliefs.

memory_query({ topic: "user preferences", limit: 5 })
// Returns: { beliefs: [...], contradictions: [...] }

Each belief includes:

• relevance: How relevant to the query
• strain: Coherence tension (higher = needs attention)
• status: 'stable' | 'needs_review' | 'high_tension'

memory_contradictions

Get all current contradictions.

memory_contradictions()
// Returns pairs of conflicting beliefs

memory_link

Explicitly define a relationship between beliefs.

memory_link({
  sourceId: "sem_123",
  targetId: "sem_456",
  relation: "contradicts"  // or: supersedes, elaborates, related, caused, caused_by
})

memory_forget

Remove a belief.

memory_forget({ id: "sem_123" })

memory_stats

Get memory health metrics.

memory_stats()
// Returns: { totalBeliefs, totalEdges, stable, needsReview, highTension, energy... }

How Strain Works

The system uses a hybrid energy model:

Logical Energy (E_logic)

• Positive constraints: Penalize disagreement between related beliefs
• Negative constraints: Penalize co-acceptance of contradicting beliefs

Geometric Energy (E_geom)

• Spring energy based on embedding distance vs. rest length
• Beliefs that drift apart semantically create tension

Total Energy: E_total = E_logic + λ * E_geom

High-strain beliefs are flagged as needs_review or high_tension.

Data Storage

By default, beliefs are stored in .sem-data/memory-index.jsonl. Set SEM_DATA_DIR env var to customize.

Theory

Based on Thagard & Verbeurgt's "Coherence as Constraint Satisfaction" - coherence is modeled as maximizing satisfaction of positive/negative constraints between elements.

See: Semantic Mesh Memory (paper)

License

MIT