Skip to main content

​
Save flow

When a memory is saved via POST /api/memories or save_memory, MemContext runs a multi-step pipeline:
  1. Expand — the content is rewritten into a more searchable sentence using an LLM
  2. Embed — an embedding is generated from the expanded content
  3. Find similar — existing current memories are searched for semantic overlap
  4. Classify — if similar memories exist, an LLM classifies the relationship
  5. Act — based on the classification, the system saves, updates, extends, or deduplicates
This means you do not need to manually manage deduplication or version chains. Save freely — the system handles it.

​
Relationship classification

When similar memories are found, the LLM classifies the relationship as one of:
ClassificationWhat happens
updateThe new memory supersedes the old one. The old memory is marked isCurrent = false and a version chain link is created.
extendThe new memory adds detail to an existing one. A relation of type extends is created between them.
similarThe new memory is related but distinct. A relation of type similar is created.
noopThe new content is a duplicate. Nothing is saved; the existing memory ID is returned.

​
Search flow

Search via GET /api/memories/search or search_memory uses hybrid retrieval:
  1. Generate query variants — the original query is expanded into alternative phrasings
  2. Embed — embeddings are created for the original query and all variants
  3. Vector search — runs against all query embeddings to find semantically similar memories
  4. Full-text search — PostgreSQL tsvector search runs in parallel on the original query
  5. Merge — results are combined using Reciprocal Rank Fusion (RRF) for a single ranked list
This approach surfaces both semantic matches (“What database does the team use?”) and exact matches (“PostgreSQL”, “carq”, “PNPM”) reliably.

​
Temporal filtering

Memories can include a validUntil timestamp. Expired memories are automatically excluded from search and list results. This is useful for:
  • Time-sensitive strategy decisions
  • Temporary experiments
  • Seasonal preferences
  • Active project states that change

​
Memory limits

Each plan has a memory limit. When the limit is reached, new save requests return 403 with the current count and limit. The check happens both before and during the save transaction to handle concurrent requests safely.