> For the complete documentation index, see [llms.txt](https://docs.graphlit.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graphlit.dev/platform/semantic-memory.md).

# Semantic Memory

Semantic memory is the ability to understand, organize, and retrieve knowledge based on meaning and relationships - not just keywords or similarity scores.

{% hint style="info" %}
**Think of human memory:** You don't remember every word of every conversation. You remember **people, places, events, and how they relate**. You can recall "What did Sarah from Acme Corp say about pricing last month?"

That's semantic memory. That's what Graphlit provides for AI.
{% endhint %}

***

## Memory Types in AI

AI agents need different types of memory, mirroring human cognition:

{% @mermaid/diagram content="graph TD
A\[AI Agent Memory] --> B\[Working Memory]
A --> C\[Long-Term Memory]
B --> B1\[Active Context<br/>LLM Context Window]
B --> B2\[Current Conversation]
C --> D\[Episodic Memory]
C --> E\[Semantic Memory]
C --> F\[Procedural Memory]
D --> D1\[Specific Events<br/>Conversation History]
E --> E1\[Facts & Relationships<br/>Knowledge Graph]
F --> F1\[How-to Knowledge<br/>Workflows]" %}

### Memory Types in Graphlit

| Type           | What It Stores                 | Graphlit Implementation                                          | Example Query                           |
| -------------- | ------------------------------ | ---------------------------------------------------------------- | --------------------------------------- |
| **Episodic**   | Specific events, experiences   | Conversation history, meeting transcripts, timestamps            | "What was discussed in Oct 15 meeting?" |
| **Semantic**   | Facts, concepts, relationships | Entity extraction (Person, Organization, Event), knowledge graph | "Who works at Acme Corp?"               |
| **Procedural** | Skills, processes, how-to      | Workflows, action sequences                                      | "How do we deploy to production?"       |
| **Working**    | Active context                 | LLM context window, current conversation                         | Current task focus                      |

{% hint style="success" %}
**Key insight:** Traditional RAG only uses working memory (context window). Graphlit provides all four memory types - a complete cognitive system.
{% endhint %}

***

## Memory Formation Cycle

Memory isn't just retrieval - it's a complete cognitive cycle:

### The Cycle Explained

1. **Ingestion**: Content enters (files, messages, meetings, web pages)
2. **Extraction**: LLM identifies entities, relationships, facts
3. **Consolidation**: Merge with existing knowledge, dedupe, organize
4. **Storage**: Persist in knowledge graph + vector store + object store
5. **Retrieval**: Query by meaning, entities, relationships, time
6. **Context Injection**: Relevant memories → LLM context window

**RAG only does steps 5-6**. Semantic memory does the complete cycle.

***

## RAG vs Semantic Memory

### The Evolution

| Era      | Approach            | What It Does            | Limitation            |
| -------- | ------------------- | ----------------------- | --------------------- |
| 2022     | Vector Search       | Similarity matching     | No understanding      |
| 2023     | RAG                 | Retrieve + generate     | Still just similarity |
| 2024     | GraphRAG            | Graph + vectors         | Complex to build      |
| **2025** | **Semantic Memory** | Meaning + relationships | Production-ready      |

### What RAG Actually Is

**Limitations**:

* Each query independent (stateless)
* No entity understanding
* No relationship tracking
* No temporal context
* Just similarity scores

**Example**: "What did Sarah say about pricing?"

* RAG searches for vectors similar to query
* Might return any mention of "Sarah" or "pricing"
* No guarantee it's the right Sarah or relevant pricing discussion

### What Semantic Memory Is

**Capabilities**:

* Understands entities (Sarah Chen = person at Acme Corp)
* Tracks relationships (Sarah works\_at Acme)
* Temporal awareness (last month vs last year)
* Stateful (knowledge builds over time)

**Same query**: "What did Sarah say about pricing?"

* Identifies "Sarah" as Person entity
* Finds all content where Sarah is mentioned
* Filters for pricing discussions
* Returns ordered by time with full context

**Result**: Actual useful answer.

***

## Knowledge Graph: The Semantic Memory Layer

Knowledge graphs ARE the semantic memory - they store entities and their relationships.

### Schema.org Foundation

Graphlit builds on **Schema.org** (JSON-LD), the industry standard:

**Benefits**:

* Standardized entity types (Person, Organization, Place, Event)
* Interoperable with other systems
* Rich vocabulary (Google, Microsoft use it)
* Extensible

**Example entity**:

```json
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Sarah Chen",
  "jobTitle": "CTO",
  "worksFor": {
    "@type": "Organization",
    "name": "Acme Corp"
  }
}
```

### How the Graph is Built

"**Observations of observable entities**" - LLM-driven extraction:

**Process**:

1. LLM reads content: "Sarah Chen from Acme Corp mentioned pricing concerns"
2. Extracts entities: Person (Sarah), Organization (Acme Corp)
3. Creates relationships: Sarah works\_at Acme Corp
4. Links to source content
5. Knowledge graph evolves

This enables multi-hop queries impossible with pure vector search: "What technical concerns have CTOs from enterprise customers raised in Q4?"

***

## How Graphlit Implements Semantic Memory

### Multi-Layer Architecture

### Temporal & Spatial Indexing

**What Graphlit tracks**:

* Content ingestion date
* Content authorship date (from metadata)
* Media timestamps ("At 5:23 in video")
* Extracted event dates ("Meeting on Oct 15")
* Geo-location (from metadata)

**Query examples that work**:

* "Content from Acme Corp in last 30 days" ✅
* "Meeting about pricing in Q4" ✅
* "At what point in video did they discuss architecture?" ✅

***

## Intelligent Query Processing

### Two-Layer Architecture

**Layer 1: Pre-Parsing** (natural language → structured filters)

```python
import json
from graphlit_api.input_types import ToolDefinitionInput

# Natural language query
query = "Show me Acme Corp pricing discussions from last week"

# Use extractText() with a tool schema to convert natural language into a ContentFilter.
tools = [
    ToolDefinitionInput(
        name="content_filter",
        description="Return a JSON object compatible with Graphlit ContentFilter.",
        schema=json.dumps(
            {
                "type": "object",
                "properties": {
                    "search": {"type": "string"},
                    "creationDateRange": {
                        "type": "object",
                        "properties": {
                            "startDate": {"type": "string"},
                            "endDate": {"type": "string"},
                        },
                    },
                },
            }
        ),
    )
]

extracted = await graphlit.client.extract_text(
    prompt="Convert the query into a ContentFilter and return it via the content_filter tool.",
    text=query,
    tools=tools,
)

filters = json.loads(extracted.extract_text[0].value)
```

**Layer 2: Hybrid Search** (vector + keyword)

```python
# Execute with extracted filters
results = await graphlit.client.query_contents(filter=filters)

# Combines:
# - Vector search: Semantic understanding
# - Keyword search: Exact entity matching
# - Date filtering: Temporal context
```

[See it in action: Filter Extraction Colab →](https://github.com/graphlit/graphlit-samples)

***

## Accessing Semantic Memory

### Pattern 1: Manual RAG (Advanced)

**Use `retrieveSources` for custom RAG pipelines:**

```python
from graphlit_api.input_types import ContentFilter

# Get LLM-optimized sources (reranked + context expanded)
sources = await graphlit.client.retrieve_sources(
    prompt="Acme Corp pricing discussions from last week",
    filter=ContentFilter(search="Acme Corp pricing"),
)

# Build your own prompt
context = "\n\n".join([s.text for s in sources.retrieve_sources.results])
prompt = f"Based on this context:\n\n{context}\n\nAnswer: What are pricing concerns?"

# Call your own LLM
```

**Features**: Reranking, context expansion (chunk → section/page), you control prompts

***

### Pattern 2: Automated RAG (Recommended)

**Use `promptConversation` for turnkey Q\&A:**

```python
# Let Graphlit handle everything
response = await graphlit.client.prompt_conversation(
    prompt="What are Acme Corp's pricing concerns?",
    id=conversation_id
)

# Behind the scenes:
# 1. Uses retrieveSources internally
# 2. Reranks for relevance
# 3. Expands context
# 4. Generates answer
# 5. Returns with citations

message = response.prompt_conversation.message

print(message.message)
for citation in message.citations or []:
    print(f"Source: {citation.content.name}")
```

**Most common pattern** - ideal for chatbots, Q\&A systems.

***

### Pattern 3: Agentic Workflows (TypeScript)

**Use `promptAgent` or `streamAgent` for autonomous agents:**

```typescript
// Agent decides when/how to retrieve
await graphlit.streamAgent(
  'Analyze Acme Corp interactions and summarize concerns',
  (event) => {
    // stream tokens + tool calls to your UI
    console.log(event);
  },
  conversationId,
);

// Agent autonomously:
// - Calls retrieveSources as tool
// - Extracts entities
// - Synthesizes findings
// - Streams response with UI events
```

**Like Zine**: Real-time streaming chat with tool transparency.

[Learn more: AI Agents Quickstart →](/tutorials/ai-agents.md)

***

### Pattern 4: Search UI (queryContents)

**For building dashboards, not RAG:**

```python
# Generic content search (not LLM-optimized)
results = await graphlit.client.query_contents(
    filter=ContentFilter(
        search="Acme Corp",
        types=[ContentTypes.FILE, ContentTypes.EMAIL]
    )
)

# Display in UI
for content in results.contents.results:
    print(f"{content.name} ({content.creation_date})")
```

***

## Practical Example: Multi-Hop Query

Query: **"What technical concerns have CTOs from enterprise customers raised in Q4?"**

### Memory Path:

**Step 1: Parse entities**

* "CTOs" → role filter
* "enterprise customers" → organization type
* "Q4" → date range

**Step 2: Query knowledge graph**

* Find all Person entities with jobTitle="CTO"
* Filter to Organization entities with type="enterprise"
* Get all content mentioning those people in Q4 date range

**Step 3: Extract topics**

* Search for "technical concerns" in filtered content
* Rank by relevance and recency

**Step 4: Return with context**

* Who said it (entity)
* When (timestamp)
* Where (content source)
* Full context

**This is impossible with RAG alone** - requires entity understanding, relationships, and temporal awareness.

***

## The "iPhoto" Analogy

Remember iPhoto? It changed how we organize photos.

**Before iPhoto**:

* Manual folders
* Hard to find: "Photos of Mom at the beach"
* No context

**After iPhoto**:

* People recognition: "Show me all photos of Mom"
* Places: "Photos taken in Hawaii"
* Events: "Christmas 2016"
* Automatic, no manual tagging

### Graphlit Does This for Company Knowledge

**Before Graphlit**:

* Files scattered across tools (Slack, email, Notion, Drive)
* Manual search in each tool
* No relationships
* Can't find "all interactions with Acme Corp"

**After Graphlit**:

* Semantic understanding: "Show me everything about Acme Corp"
* Entity recognition: People, companies, events automatically
* Unified search across all tools
* Contextual: Knows relationships and time

> **"Like iPhoto for your company's knowledge"**

***

## Use Cases Enabled

### Sales Agent (Episodic + Semantic Memory)

```python
# Episodic: Past conversations
conversations = await graphlit.client.query_contents(filter=ContentFilter(
    search="Acme Corp",
    types=[ContentTypes.MESSAGE, ContentTypes.EMAIL]
))

# Semantic: Organization relationships
entities = await graphlit.client.query_persons(filter=PersonFilter(
    search="Acme Corp"
))

# Combined: Complete deal context
# - All people contacted
# - All conversations
# - Key objections and requirements
# - Timeline of engagement
```

***

### Developer Agent (Episodic + Semantic Memory)

```python
# Episodic: Specific PR discussion
pr_context = await graphlit.client.query_contents(filter=ContentFilter(
    search="PR #247"
))

# Semantic: Related architecture decisions
architecture = await graphlit.client.query_contents(filter=ContentFilter(
    search="Redis caching architecture"
))

# Combined: Root cause analysis
# - PR discussion
# - Related Slack threads
# - Meeting where decision was made
# - Who made it and why
```

***

### Customer Intelligence (Episodic + Semantic)

Combine conversation history (episodic) with entity relationships (semantic) to understand customer health:

* Email sentiment over time
* Support ticket trends
* Product usage patterns
* Meeting sentiment
* Churn risk signals

All connected through knowledge graph.

***

## Real-World Example: Zine

[Zine](https://www.zine.ai) is built 100% on Graphlit's semantic memory.

**What users ask**:

> "What did Acme Corp say about pricing in our last 3 calls?"

**What happens** (powered by Graphlit):

1. Identify "Acme Corp" as Organization entity
2. Find all Event entities (calls) with Acme Corp
3. Filter last 3 calls
4. Search meeting transcripts for "pricing"
5. Return quotes with timestamps and context

**Result**: Answer in seconds, not hours of manual searching.

[See Zine's architecture →](/examples/zine-case-study.md)

***

## Why This Matters for Production AI

### Traditional Approach (RAG)

```
Ingest documents
↓
Create embeddings
↓
Vector search
↓
Hope it works
```

**Problems**:

* Tweak embeddings models endlessly
* Results "meh" - similar but not relevant
* Can't query by entity, time, or relationship
* Agents forget context
* Complex workflows don't work

***

### Semantic Memory Approach

```
Connect tools
↓
Auto-extract entities & relationships
↓
Build knowledge graph
↓
Query by meaning
↓
Agents remember context
```

**Benefits**:

* Build features, not infrastructure
* Results are relevant and contextual
* Query by entity, time, relationship
* Agents have true memory
* Complex workflows just work

***

## The 2025 Shift

### From:

* "Let's build a RAG system"
* "What vector database should we use?"
* "How do we chunk documents?"
* "Which embedding model is best?"

### To:

* "Let's give our AI semantic memory"
* "Connect our tools to Graphlit"
* "Query by entities and relationships"
* "Build agents that remember"

***

## Key Principles

1. **Memory > Search** - Don't just search, remember
2. **Entities > Documents** - Track people, companies, events
3. **Context > Chunks** - Preserve relationships and time
4. **Meaning > Keywords** - Semantic understanding
5. **Agents > Chatbots** - Persistent memory across sessions

***

## Learn More

**Build with Semantic Memory:**

* [Quickstart: Your First Agent](/getting-started/quickstart.md) - Build a streaming agent in 7 minutes
* [AI Agents](/tutorials/ai-agents.md) - Build agents with memory
* [Knowledge Graph](/tutorials/knowledge-graph.md) - Extract entities
* [Context Engineering](/tutorials/context-engineering.md) - Optimize memory

**Understand the Platform:**

* [Platform Overview](/getting-started/overview.md) - Complete platform capabilities
* [Key Concepts](/platform/key-concepts.md) - Data model overview
* [Connectors](https://github.com/graphlit/graphlit-docs/blob/main/platform/connectors.md) - 30+ integrations
* [AI Models](/platform/models.md) - GPT-5, Claude 4.5, Gemini 2.5

**See It in Production:**

* [Zine Case Study](/examples/zine-case-study.md) - Real-world patterns
* [Sample Apps](https://github.com/graphlit/graphlit-samples) - 60+ examples

***

**Give your AI semantic memory. Build with Graphlit.**