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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.graphlit.dev/platform/semantic-memory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.