Skip to main content

​
Memory Types

MemMachine works as an intelligent memory layer on top of a user’s Agentic LLM experience. It gathers input via Python APIs in a Memory Instance, then determines if that input is profile, short-term and/or long-term:
  • Semantic memory consists of information specific to the user and their experience.
  • Episodic memory consists of both short-term and long-term memory function:
    • Short-term memory consists of episodic memory and summaries of the episodic memory. A raw episode consists of 1 message.
    • Long-term memory consists of a batch of episodes that is generated from the short-term memories. The Episode batch is then ranked using a Reranker and deduplicated for the most frequent hits.

​
How does MemMachine sort into it’s Memory Types?

MemMachine utilizes an embedder to break apart user/agent language into distinct computer understandable derivatives. These derivatives are then passed through a re-ranker which compares the results to those found in the long-term memory buckets, then returns the top, sorted matches. After the re-ranker completes it’s activity, memory is stored into an associated database.

​
Semantic Memory

Semantic, or profile memory specifically focuses on information and data specific to a user and their experience. The data is stored in an SQL database, such as PostgreSQL. Memory Storage Process
  1. Raw user messages go into history table
  2. An LLM analyzes conversations to extract meaningful knowledge
  3. Structured knowledge gets stored into the prof table with vector embeddings
  4. The citations table links each piece of knowledge back to its source conversations
Memory Retrieval Process
  1. Query: User asks a question or system needs context
  2. Semantic Search: System uses vector embeddings to find relevant knowledge
  3. Retrieval: Returns matching profile entries with their associated conversation sources
  4. Context: Citations provide traceability back to original conversations

​
Database Semantic Memory Table Structures

MemMachine is built on a PostgreSQL database, which uses the pgvector extension to perform an efficient vector similarity search. Think of this as a way to instantly find similar or related information. The Semantic Memory system uses two main tables to organize user profiles and their sources. Note that raw conversation history is now managed by the separate Episode Store, and semantic features cite those episodes directly.
Description: This is the main table for storing a user’s profile and their features. We use vector embeddings in this table to give us a powerful way to perform semantic searches.Purpose: This is where we store a user’s profile information. We use a two-level key-value structure (tag → feature → value) and vector embeddings to make it easy to find relevant user characteristics quickly through a semantic search.Here’s an example Semantic table (prof):
Column   |           Type           | Nullable |             Default              
------------+--------------------------+----------+----------------------------------
 id         | integer                  | not null | nextval('prof_id_seq'::regclass)
 set_id     | text                     | not null | 
 category   | text                     | not null |
 tag        | text                     | not null | 'Miscellaneous'::text
 feature    | text                     | not null | 
 value      | text                     | not null | 
 create_at  | timestamp with time zone | not null | CURRENT_TIMESTAMP
 update_at  | timestamp with time zone | not null | CURRENT_TIMESTAMP
 embedding  | vector                   | not null | 
 metadata   | jsonb                    | not null | '{}'::jsonb
Here are the fields you’ll find in this table:
FieldExplanation
idUnique identifier for each knowledge entry.
set_idA unique ID organizing the information (e.g., grouping by user or role).
categoryThe category of information (e.g., “user_profile”, “role_definition”).
tagA high-level categorization (e.g., “Preferences”, “Skills”, “Background”).
featureAn executive summary of the information (e.g., “likes_pizza”, “programming_language”)
valueDetailed content of the knowledge (e.g., “Margherita with extra cheese”, “Python, JavaScript, Go”)
create_atThis is a timestamp for when the listing in the table was created.
update_atThis is a timestamp for when the listing in the table was last updated.
embeddingMemMachine creates a numerical fingerprint (vector embedding) for each memory, enabling smart, meaning-based searches.
metadataA JSONB field for storing additional structured information about the knowledge entry.
Vector Dimension MismatchVector dimension in a memory table must never change. If you switch to an embedding model that generates vectors of a different dimension (length), all similarity searches will immediately fail.Solution: You must either re-embed all existing memory data with the new model, or use a separate table/namespace for the new model’s embeddings.