> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remem.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Layer

> Extract facts, discover entities, and build a knowledge graph from your documents.

# Memory Layer

The Memory Layer automatically extracts discrete **facts** from your documents and organizes them into a structured knowledge graph of **entities** and **relationships**. Think of it as turning unstructured documents into a queryable knowledge base.

## Overview

<CardGroup cols={2}>
  <Card title="Facts" icon="lightbulb">
    Atomic statements extracted from documents. Typed, confidence-scored, and temporally aware.

    Example: *"The API rate limit is 100 req/min"*
  </Card>

  <Card title="Entities" icon="users">
    People, organizations, projects, and concepts referenced by facts. Automatically deduplicated across documents.

    Example: *Acme Corp* (resolved from "Acme", "Acme Corporation")
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Document Ingested">
    A document completes normal ingestion (chunking, embedding, classification).
  </Step>

  <Step title="Fact Extraction">
    An async memory worker sends the document content to Grok for fact extraction. Each fact is typed (`fact`, `preference`, `episode`, `decision`) and confidence-scored.
  </Step>

  <Step title="Entity Resolution">
    Extracted entity mentions are resolved against existing entities using HMAC-based exact matching and type-aware deduplication.
  </Step>

  <Step title="Relationship Discovery">
    New facts are compared against existing facts sharing the same entities. Relationships (`updates`, `extends`, `derives`, `contradicts`) are discovered via LLM comparison.
  </Step>
</Steps>

## Fact Types

| Type         | Description               | Example                                      |
| ------------ | ------------------------- | -------------------------------------------- |
| `fact`       | Objective statement       | "PostgreSQL 16 is the primary database"      |
| `preference` | User or system preference | "Team prefers TypeScript for new services"   |
| `episode`    | Event or occurrence       | "Production outage on Feb 10 lasted 2 hours" |
| `decision`   | Decision made             | "Chose Redis over Memcached for caching"     |

## API Endpoints

### List Entities

```bash theme={null}
curl https://api.remem.io/v1/entities \
  -H "X-API-Key: vlt_..." \
  -G -d "type=person" -d "limit=20"
```

**Response:**

```json theme={null}
{
  "entities": [
    {
      "id": "e1a2b3c4-...",
      "name": "Jane Smith",
      "entity_type": "person",
      "mention_count": 12,
      "fact_count": 5,
      "first_seen": "2026-01-15T10:30:00Z",
      "last_mentioned": "2026-02-20T14:22:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

| Parameter | Type    | Default | Description           |
| --------- | ------- | ------- | --------------------- |
| `type`    | string  | -       | Filter by entity type |
| `limit`   | integer | 50      | Max results (1-200)   |
| `offset`  | integer | 0       | Pagination offset     |

### Get Entity Facts

```bash theme={null}
curl https://api.remem.io/v1/entities/ENTITY_ID/facts \
  -H "X-API-Key: vlt_..."
```

| Parameter     | Type    | Default | Description                                         |
| ------------- | ------- | ------- | --------------------------------------------------- |
| `latest_only` | boolean | `true`  | Only return current (non-superseded) facts          |
| `fact_type`   | string  | -       | Filter: `fact`, `preference`, `episode`, `decision` |

### Trigger Fact Extraction

Manually re-extract facts from a completed document:

```bash theme={null}
curl -X POST https://api.remem.io/v1/documents/DOC_ID/extract-facts \
  -H "X-API-Key: vlt_..."
```

Returns `202 Accepted` with extraction status.

### Query with Facts

Include facts in normal query responses:

```bash theme={null}
curl -X POST https://api.remem.io/v1/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vlt_..." \
  -d '{
    "query": "What tech stack does Acme use?",
    "include_facts": true,
    "entity": "Acme Corp"
  }'
```

See [Querying with Facts](/querying#querying-with-facts) for response format details.

## MCP Tools

The following MCP tools are available for the Memory Layer:

| Tool                     | Description                 |
| ------------------------ | --------------------------- |
| `remem_memory_query`     | Query facts by topic/entity |
| `remem_list_entities`    | Browse entities             |
| `remem_get_entity_facts` | Get facts for an entity     |
| `remem_extract_facts`    | Trigger extraction          |

See [MCP Integration](/mcp-integration#memory-layer-tools) for configuration.

## CLI Commands

```bash theme={null}
remem entities                          # List all entities
remem entities --type person            # Filter by type
remem entity-facts ENTITY_UUID          # Get facts
remem extract-facts DOCUMENT_UUID       # Trigger extraction
remem query "topic" --facts --entity X  # Query with facts
```

See [CLI](/cli) for full command reference.

## Encryption

All fact content and entity names are encrypted at rest using the tenant's DEK (same envelope encryption as documents). Structural metadata (fact\_type, confidence, is\_latest, timestamps) remain in plaintext for filtered queries. Entity deduplication uses HKDF-derived HMAC hashes — no plaintext comparison needed.