# @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

```bash
# 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`:

```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.

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

### `memory_query`
Search for relevant beliefs.

```typescript
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.

```typescript
memory_contradictions()
// Returns pairs of conflicting beliefs
```

### `memory_link`
Explicitly define a relationship between beliefs.

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

### `memory_forget`
Remove a belief.

```typescript
memory_forget({ id: "sem_123" })
```

### `memory_stats`
Get memory health metrics.

```typescript
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)](./paper/semantic-mesh-memory-academic.md)

## License

MIT