How memory works

In plain terms: You drop in thoughts as they come. Eigen Mesh organizes them in the background and makes them searchable later — in the browser or through connected AI tools — without you filing, tagging, or repeating context every session.

Who this is for

• End users capturing and searching memories in the browser or via connected AI tools
• Integrators who want to understand what happens after capture_thought and retrieve_thoughts

The pipeline in everyday terms

1. Capture — Type or dictate a thought. No structure required upfront.
2. Organize — Eigen Mesh classifies, links, and indexes what you saved automatically.
3. Retrieve — Search or ask a question; relevant memories surface with citations.
4. Consolidate — Overnight, less important memories fade while connections strengthen.

You own your data in all deployment modes. Self-hosted operators control infrastructure; managed users retain export/delete guarantees. See Deployment model.

Technical details

Pipeline overview

flowchart LR
  Capture[Capture raw thought]
  Enrich[Enrich classify embed]
  Store[(Postgres pgvector)]
  Graph[(Apache AGE graph)]
  Materialize[Materialize neighbors bundles]
  Retrieve[Hybrid retrieval rerank]
  Compose[Grounded answer]
  Sleep[Nightly consolidation]

  Capture --> Enrich
  Enrich --> Store
  Enrich --> Graph
  Graph --> Materialize
  Materialize --> Retrieve
  Store --> Retrieve
  Retrieve --> Compose
  Store --> Sleep
  Graph --> Sleep

1. Capture

You submit unstructured text (type or dictate in the browser). Dictation uses server-side speech-to-text (billed like other LLM calls on platform credits). No filing, tagging, or structure required upfront.

• Browser UI: /capture with optional offline queue (IndexedDB + Background Sync)
• MCP: capture_thought
• REST: POST /api/capture/submit

2. Enrichment (ingestion)

On persist, the server:

1. Normalizes and classifies the text (ontology categories: thought, task, idea, reference, date, person)
2. Computes an embedding and stores it in pgvector (never returned to tools or LLM prompts)
3. Builds lexical search tokens (tsvector / FTS) and lexical_text for keyword recall
4. Syncs nodes and edges in Apache AGE (OpenCypher graph in the same Postgres instance)
5. Materializes thought_neighbor, thought_entity, and community bundles for fast retrieval
6. Extracts entities and relations; logs activity with transparent per-call cost

Ontology profile refreshes every 10th captured thought.

3. Retrieval

When you search or ask a question:

1. Vector channel — pgvector approximate nearest neighbor on query embedding
2. Lexical channel — PostgreSQL full-text search over lexical_text and cues
3. Graph channel — precomputed neighbors, entity-anchored paths, and community bundles (no live AGE traversal at query time)
4. Fusion — weighted merge of channels, then LLM listwise rerank over the top candidate pool

Surfaces: MCP retrieve_thoughts, REST /api/retrieval/search, in-app Chat UI.

Browse recent thoughts via MCP retrieve_thoughts with order=created_at (no query).

4. Grounded answers

The in-app Chat agent calls retrieve_thoughts, then composes a natural-language answer with citations in the agent loop. HTTP MCP clients do the same two-step pattern in their own client — there is no answer_question MCP tool.

The LLM sees text and scores only — not embedding vectors (Embeddings boundary).

5. Consolidation (sleep)

Nightly pg_cron triggers consolidation:

Salience also bumps when you access memories during the day (reconsolidation).

Troubleshooting

See Troubleshooting for retrieval and capture issues.

Next steps

• Architecture overview — system domains
• MCP overview — connect your assistant
• Embeddings boundary — security policy