​

Advanced Augmentation

​

What It Does

1. Reads the full conversation (user messages and AI responses)
2. Identifies facts, preferences, skills, and attributes
3. Extracts semantic triples (subject-predicate-object relationships)
4. Generates vector embeddings for semantic search
5. Stores everything in your memory backend

​

How It Works

from memori import Memori
from openai import OpenAI

client = OpenAI()
mem = Memori().llm.register(client)
mem.attribution(entity_id="user_123", process_id="my_agent")

# This returns immediately — no augmentation delay
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "I love hiking in the mountains."}
    ]
)
print(response.choices[0].message.content)

# Only needed in short-lived scripts
mem.augmentation.wait()

​

Augmentation Pipeline

1. Conversation capture — Your app makes an LLM call through the wrapped client
2. Immediate response — Memori returns the LLM response without delay
3. Background queueing — The conversation is queued for asynchronous processing
4. Memory extraction — The augmentation engine analyzes the conversation
5. Batched writes — Extracted memories are written to storage in batches

​

Implementation Details

​

Worker Pool

• Max workers: 50 concurrent augmentation tasks (configurable via manager.max_workers)
• Semaphore-based concurrency control to prevent resource exhaustion
• Event loop management with dedicated thread for async operations

​

Database Writer

• Batch size: 100 write operations (configurable via manager.db_writer_batch_size)
• Batch timeout: 0.1 seconds (configurable via manager.db_writer_batch_timeout)
• Queue size: 1000 pending writes (configurable via manager.db_writer_queue_size)
• Automatic flushing when batch is full or timeout expires

​

Message Selection Strategy

1. With conversation summary: Sends only the most recent user-assistant exchange
2. Without summary: Sends all messages in the conversation

​

Extraction Types

​

Entity-Level Memories

• Full text content
• Vector embedding (384 dimensions for all-MiniLM-L6-v2)
• Creation timestamp
• Entity association

• Subject (e.g., “user”)
• Predicate (e.g., “uses”)
• Object (e.g., “PostgreSQL”)
• Mention count (increments on duplicate)
• Last mentioned timestamp

​

Process-Level Memories

• Attribute name
• Attribute value
• Process association

​

Semantic Triples

​

Triple Storage

1. Subjects — Unique subjects (e.g., “user”, “Alice”)
2. Predicates — Unique predicates (e.g., “uses”, “prefers”)
3. Objects — Unique objects (e.g., “PostgreSQL”, “dark mode”)
4. Knowledge Graph — Links subjects, predicates, and objects with metadata

​

Embeddings

• Extracted facts
• Facts derived from semantic triples

from memori.embeddings import embed_texts

# Generate embeddings for a list of texts
embeddings = await embed_texts(
    ["User prefers dark mode", "User uses PostgreSQL"],
    model="all-MiniLM-L6-v2",
    async_=True
)
# Returns: list of 384-dimensional vectors

​

Context Recall

1. Intercepts the outbound LLM call
2. Embeds the user’s query
3. Uses semantic search to find entity facts matching the query
4. Ranks facts by cosine similarity via FAISS
5. Injects the most relevant facts into the system prompt
6. Forwards the enriched request to the LLM provider

• FAISS IndexFlatIP (inner product after L2 normalization = cosine similarity)
• Exact search (not approximate)
• Filters by recall_relevance_threshold (default: 0.1)

• Recall implementation: memori/memory/recall.py:180-226
• FAISS integration: memori/search/_faiss.py:81-122

​

Waiting for Augmentation

from memori import Memori
from openai import OpenAI

client = OpenAI()
mem = Memori().llm.register(client)
mem.attribution(entity_id="user_123", process_id="my_agent")

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "I use Python"}]
)

# Wait for augmentation to complete (with 30-second timeout)
if mem.augmentation.wait(timeout=30):
    print("Augmentation complete!")
else:
    print("Augmentation timed out")

1. Waits for all pending futures to complete
2. Waits for the database writer queue to drain
3. Waits an additional 2x batch timeout for final processing
4. Returns True if successful, False if timeout exceeded

​

Error Handling

​

Quota Exceeded

from memori import QuotaExceededError

try:
    response = client.chat.completions.create(...)
except QuotaExceededError as e:
    print(f"Quota exceeded: {e}")
    # Conversations still work, but augmentation is paused

​

Augmentation Failures

• Error is logged
• Other augmentation tasks continue
• Your LLM calls are not affected

​

Configuration

from memori import Memori

mem = Memori()

# Access augmentation manager after initialization
mem.augmentation.max_workers = 100           # Increase parallelism
mem.augmentation.db_writer_batch_size = 200  # Larger batches
mem.augmentation.db_writer_batch_timeout = 0.5  # Wait longer before flush

​

Metadata Collection

• SDK version — Python SDK version
• LLM provider — OpenAI, Anthropic, Google, etc.
• LLM model — gpt-4o-mini, claude-3-sonnet, etc.
• Framework — LangChain, PydanticAI, etc.
• Platform — FastAPI, Django, etc.
• Storage dialect — PostgreSQL, SQLite, MongoDB, etc.

{
  "conversation": {
    "messages": [
      {"role": "user", "content": "..."},
      {"role": "assistant", "content": "..."}
    ],
    "summary": "Previous conversation context"
  },
  "meta": {
    "attribution": {
      "entity": {"id": "hashed_entity_id"},
      "process": {"id": "hashed_process_id"}
    },
    "sdk": {"lang": "python", "version": "1.0.0"},
    "llm": {
      "model": {
        "provider": "openai",
        "version": "gpt-4o-mini"
      }
    },
    "storage": {"dialect": "postgresql"}
  }
}