Entities, Facts, and Topics

When you save a memory, MemNexus doesn't just store the text. It runs an extraction pipeline that pulls out structured knowledge: facts, entities, and topics. These form a knowledge graph layer that sits underneath your memories and makes search significantly more powerful.

This guide explains what the extraction layer does, why it matters, and how to query it directly.

What gets extracted

Facts

Facts are discrete pieces of structured knowledge extracted from your memory content.

When you save a memory like:

"We use Redis for session storage instead of the database. Connection pool is set to 20 connections in production — we found 50 caused latency spikes under load."

The extraction pipeline identifies facts like:

• session storage uses Redis
• Redis connection pool size: 20 (production)
• 50 connections caused latency spikes

These are stored as structured entries that can be searched separately from the raw memory content.

Entities

Entities are named things: services, people, repositories, issue numbers, commit hashes, PRs. When your memory mentions #341, commit e4a1c02, auth-service, or @Jamie, those get extracted and linked via the knowledge graph.

This means you can find memories by entity — "show me everything that mentions issue #341" — even if the memory content doesn't phrase it in a way that keyword search would find.

Topics

Topics are category tags. Some are added manually with --topics; most are extracted automatically from content. If your memory discusses authentication and JWT tokens, topics like authentication and jwt are extracted without you having to add them.

Why this matters for search

The default search mode (unified) searches across content, extracted facts, and entities simultaneously. This is why searching for "rate limit" finds memories that mention rate limiting even if they use different wording — because the fact extraction has normalized the concepts.

But when you need to find specific knowledge, searching the extracted layers directly gives you more precision.

Searching facts

# Find specific knowledge extracted from memories
mx memories search --query "connection pool" --mode facts

# Or query the facts store directly
mx facts search --query "Redis connection pool"

Facts search is useful when you know there's a specific configuration value, limit, or decision somewhere in your memories and you want to find it fast.

Searching by topic

# Find memories tagged with specific topics
mx topics search --query "authentication"

# Discover topics related to one you know about
mx topics discover-related --topic "rate-limiting"

discover-related uses the graph relationships to find topics that often appear together with your query. If you search for rate-limiting, you might discover redis, api-gateway, throttling, and connection-pool are all related in your workspace. This helps when you're not sure what terms to search.

Entity lookup

When you need everything connected to a specific thing — a service, a person, an issue:

# Find all memories about a specific issue
mx memories search --query "issue #341"

# Find memories that mention a specific service
mx memories search --query "payments-service"

Because entities are extracted and indexed from content, this works even if the memory was written before you knew you'd want to search by that entity.

Writing memories that extract well

The extraction pipeline works best when your memories are specific and use explicit names. Compare:

Extracts poorly:

"Fixed the timing issue in that auth thing. Turned out to be the same problem we had before."

Extracts well:

"Fixed race condition in token-refresh-service (PR #412). Two concurrent requests could both observe an expired access token and both call the refresh endpoint simultaneously. Fixed with a Redis distributed lock (5-second TTL, key: token_refresh:{user_id}). Root cause: no locking around the check-then-refresh pattern. This matches the incident from issue #298 in December."

The second version extracts:

• Entity: token-refresh-service, PR #412, issue #298
• Fact: Redis lock TTL: 5 seconds, lock key format: token_refresh:{user_id}
• Topic: race-condition, token-refresh, redis, authentication

Those extracted facts and entities make this memory findable six months later even if you can't remember the exact wording.

The graph layer

Beyond individual extractions, the knowledge graph connects memories through relationships. Memories that share entities are linked. Topics that co-occur get relationship edges. This means:

• Searching for auth-service returns memories that explicitly mention it, but also surfaces memories about things that are closely related to auth-service in your workspace
• topics discover-related works because it follows graph edges rather than doing keyword matching
• memories search --timeline can show how understanding of a topic evolved, because the temporal relationships between memories are part of the graph

You don't interact with the graph directly for most use cases — the unified search mode uses it automatically. But when keyword search isn't finding what you need, querying the structured layers is how you dig deeper.

Practical example: finding a forgotten decision

You need to know what database connection pool size you settled on for production. You don't remember which memory captured it or when.

# Option 1: Unified search (searches content + facts + entities)
mx memories search --query "database connection pool production"

# Option 2: Facts-only search (finds extracted knowledge)
mx memories search --query "connection pool size" --mode facts

# Option 3: Direct facts query
mx facts search --query "connection pool"

Option 2 or 3 will surface this faster if the specific value was extracted as a fact. Option 1 will find it if it's in the content but wasn't extracted as a structured fact.

Practical example: understanding a topic area

You're about to work on the rate limiting system and want to understand the full landscape of related topics in your workspace:

# Discover what's related to rate-limiting in your memory graph
mx topics discover-related --topic "rate-limiting"

This might surface redis, api-gateway, throttling, connection-pool, circuit-breaker — giving you a map of related areas. Then you can search each one:

mx memories digest --query "rate limiting redis api-gateway" --digest-format structured

Now your AI has a synthesized overview of everything your team knows about rate limiting, connection pools, and how they interact with the API gateway — all from a standing start.

Checking what's been extracted from a memory

After saving a memory, you can see what was extracted from it:

# Get full memory details including extracted facts
mx memories get <memory-id>

# List extracted facts for a specific memory
mx facts list --memory-id <memory-id>

This is useful for verifying that important facts were correctly extracted, or for understanding why a memory surfaced in a search.

Next steps

• Capturing memories that actually help — How to write memory content that extracts well
• recap vs digest vs search — When to use each retrieval method
• Search reference — Full search syntax and options