> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Temporal Memory Graph

> From memory lists to knowledge graphs: how Experts build persistent structured cognition

When you tell an Expert "I work on B2B SaaS," it remembers. When you later say "We recently pivoted to B2C," it doesn't simply overwrite — it understands this as a change over time: you used to do B2B, and now you do B2C.

This is what "temporal" means: memories have a time dimension, facts have lifecycles, and changes are preserved rather than overwritten.

## Four-Layer Memory Pipeline

Memory flows from user-visible lists to AI-distilled knowledge graphs across four layers:

<Steps>
  <Step title="Memory List (user-visible)">
    You can view, add, edit, delete, enable, or disable each memory entry. This is the layer you interact with directly, with full control.
  </Step>

  <Step title="Evidence Snapshots (immutable)">
    When each memory is created, the system generates an immutable evidence snapshot — the original basis for "why this was remembered." Even if the memory is later modified, the evidence is always preserved.
  </Step>

  <Step title="Core Facts (AI-distilled)">
    Periodic consolidation processes distill evidence into structured facts — entities (people, concepts, tools, projects) and relationships (preferences, usage, affiliation). **Core facts are a read-time projection of currently active facts, not a second copy.**
  </Step>

  <Step title="Memory Graph (visualization)">
    Core facts form a time-tagged knowledge graph. Each node is an entity, each edge is a relationship. You can visually browse it in the UI.
  </Step>
</Steps>

<Tip>
  Consolidation **never modifies your memory list**. Memories you add always remain exactly as you added them — core facts are simply structured projections distilled by AI from them.
</Tip>

## Entity Types

Entities in the memory graph fall into 10 types:

| Type         | Meaning                          | Examples                         |
| ------------ | -------------------------------- | -------------------------------- |
| Person       | People you mention               | "Manager Zhang," "my co-founder" |
| Preference   | Your explicit preferences        | "Prefers TypeScript"             |
| Constraint   | Objective limitations            | "Budget of 50K," "3-person team" |
| Decision     | Explicit choices made            | "Using Next.js, not Remix"       |
| Project      | Things you're working on         | "SaaS dashboard redesign"        |
| Tool         | Tools and frameworks used        | "React," "PostgreSQL"            |
| Concept      | Abstract concepts or principles  | "Simplicity first"               |
| Organization | Teams or companies you belong to | "Startup team"                   |

Entity names and fact descriptions follow the language of the evidence — Chinese memories produce Chinese facts, English memories produce English facts.

## Contradiction Handling: No Deletion, Only Iteration

When new information contradicts existing facts, the system's approach is not "delete the old one":

1. The old fact is given an end timestamp ("Until last week, the user was using JavaScript")
2. The new fact begins from the current moment ("Starting this week, the user switched to TypeScript")
3. **History is always preserved** — the Expert can recall the complete evolution of decisions

## Memory Consolidation (Dream)

Memory distillation is performed through two speeds of "consolidation" processes:

<CardGroup cols={2}>
  <Card title="Light Consolidation (post-conversation)" icon="bolt">
    Key memories are extracted immediately after each quality conversation. Upon successful extraction, best-effort distillation into the graph follows. Fast, immediate, no information lost.
  </Card>

  <Card title="Deep Consolidation (scheduled)" icon="clock">
    A periodic scheduler scans unprocessed evidence and distills in batches. Each batch is size-limited to avoid single-call timeouts. Mid-process failures can be resumed — already processed portions are not lost.
  </Card>
</CardGroup>

Every graph change is written to an operation journal as before/after snapshots, forming a complete change audit trail. Any consolidation batch can be atomically reverted.

## Retrieval: Bounded and Efficient

When an Expert needs to recall, it doesn't search all memories — it follows a precise four-step retrieval:

<Steps>
  <Step title="Candidate screening">
    Based on the current conversation content, the most relevant candidate memories are screened (upper limit of 30).
  </Step>

  <Step title="Graph expansion">
    A 1-hop expansion is performed on entities in the candidates within the graph — finding directly related facts.
  </Step>

  <Step title="Re-ranking">
    Results are re-ranked by relevance, recency, and importance.
  </Step>

  <Step title="Context injection">
    The top 20 entries (not exceeding 2,000 tokens) are injected into the current conversation context.
  </Step>
</Steps>

<Note>
  "Bounded" is a key design decision. Injecting all memories wholesale not only wastes tokens but drowns out truly relevant information. 20 carefully selected memories are more useful than 200 generic ones. On retrieval failure, the system automatically degrades to a deterministic "latest 20" strategy.
</Note>

## User Control

Control of the memory system is entirely in your hands. On the Expert's evolution page, you can manage memories through three tabs:

<CardGroup cols={3}>
  <Card title="Memory List" icon="list">
    View, add, edit, delete, enable/disable each memory entry. This is the layer users directly operate.
  </Card>

  <Card title="Core Memories" icon="brain">
    View AI-distilled structured facts — entities, relationships, timestamps. Read-only view.
  </Card>

  <Card title="Memory Graph" icon="diagram-project">
    A visual knowledge network. Nodes are entities, edges are relationships — see the complete picture of the Expert's understanding of you at a glance.
  </Card>
</CardGroup>

You can also enable **temporary conversation** mode — the current conversation won't read memories or create new ones, suitable for sensitive topics.

## Isolation and Privacy

Memories are strictly isolated by Expert × User. User A's memories with Expert X are completely independent from User B's memories with Expert X. Cross-boundary access always returns 404 — non-enumerable, it's impossible to probe whether someone else has memories.

An Expert will never "cross-contaminate" memories — what you discuss with an Expert can never be obtained by another user through memory retrieval.