Semantic Layers

Why Layers Exist

Semantic search works well for finding memories that are conceptually close to a query. But it struggles with certain kinds of recall. A query like “What programming concepts have I discussed?” may not surface a specific memory like “Discussed Rust’s borrow checker in the Friday meeting” because the two are semantically distant.

MemLayer solves this by organizing memories into a hierarchy of four semantic layers. Each memory is assigned a layer based on its level of abstraction, and memories at different layers are linked through parent-child relationships. This creates multiple paths to reach any given memory.

The Four Layers

Layers are numbered 0 through 3 in the API, from most abstract to most specific:

Layer	Name	What It Represents	Example
0	Domain	Abstract categories of knowledge	”risk management”
1	Concept	Grouped, related knowledge within a domain	”financial instruments”
2	Fact	A specific, concrete piece of knowledge	”worked on instrument X at Acme Corp”
3	Episode	A time-bound event or interaction	”discussed instrument X in the Tuesday standup”

Hierarchy Example

Memories form a tree structure through parent-child relationships:

"Programming" (Domain, layer 0)
  └── "Type Systems" (Concept, layer 1)
        ├── "Haskell has algebraic data types" (Fact, layer 2)
        │     └── "Explained ADTs to the team on Monday" (Episode, layer 3)
        └── "Rust has ownership types" (Fact, layer 2)

A semantic search for “memory safety in systems programming” might directly match the Rust fact. From there, graph traversal discovers the parent concept “Type Systems”, the sibling fact about Haskell, and the domain “Programming” — providing richer context than semantic search alone.

How Layers Are Assigned

When content enters MemLayer through the retain operation, an LLM classifies each extracted entity into a layer based on abstraction level:

• Domain: Broad, categorical statements. Rarely from user input directly — more often created by reflect.
• Concept: Statements about a topic area that group multiple facts.
• Fact: Concrete, specific knowledge. Most user-provided content falls here.
• Episode: Events tied to a specific time or interaction.

How Layers Improve Recall

The hierarchy enables three navigation patterns that pure semantic search cannot:

Navigate up: From a specific fact, follow parent links to find the broader concept or domain.

Drill down: From a domain or concept, follow child links to find specific facts and episodes.

Traverse sideways: Through a shared parent, discover sibling memories. “Haskell’s type classes” and “Rust’s trait system” may not match each other in vector space, but they’re both children of “Type Systems.”

Filtering by Layer

Both the recall endpoint and the memories endpoint support a layer query parameter:

GET /api/v1/recall?query=programming&layer=1

This returns only Concept-level memories, filtering out specific facts and episodes. Valid values: 0 (Domain), 1 (Concept), 2 (Fact), 3 (Episode).