Skip to main content

​
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

Facts

Atomic statements extracted from documents. Typed, confidence-scored, and temporally aware.Example: “The API rate limit is 100 req/min”

Entities

People, organizations, projects, and concepts referenced by facts. Automatically deduplicated across documents.Example: Acme Corp (resolved from “Acme”, “Acme Corporation”)

​
How It Works

1

Document Ingested

A document completes normal ingestion (chunking, embedding, classification).
2

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

Entity Resolution

Extracted entity mentions are resolved against existing entities using HMAC-based exact matching and type-aware deduplication.
4

Relationship Discovery

New facts are compared against existing facts sharing the same entities. Relationships (updates, extends, derives, contradicts) are discovered via LLM comparison.

​
Fact Types

TypeDescriptionExample
factObjective statement”PostgreSQL 16 is the primary database”
preferenceUser or system preference”Team prefers TypeScript for new services”
episodeEvent or occurrence”Production outage on Feb 10 lasted 2 hours”
decisionDecision made”Chose Redis over Memcached for caching”

​
API Endpoints

​
List Entities

curl https://api.remem.io/v1/entities \
  -H "X-API-Key: vlt_..." \
  -G -d "type=person" -d "limit=20"
Response: 
{
  "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
}
ParameterTypeDefaultDescription
typestring-Filter by entity type
limitinteger50Max results (1-200)
offsetinteger0Pagination offset

​
Get Entity Facts

curl https://api.remem.io/v1/entities/ENTITY_ID/facts \
  -H "X-API-Key: vlt_..."
ParameterTypeDefaultDescription
latest_onlybooleantrueOnly return current (non-superseded) facts
fact_typestring-Filter: fact, preference, episode, decision

​
Trigger Fact Extraction

Manually re-extract facts from a completed document: 
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: 
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 for response format details.

​
MCP Tools

The following MCP tools are available for the Memory Layer:
ToolDescription
remem_memory_queryQuery facts by topic/entity
remem_list_entitiesBrowse entities
remem_get_entity_factsGet facts for an entity
remem_extract_factsTrigger extraction
See MCP Integration for configuration.

​
CLI Commands

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