Meta tags:
description=Hierarchical, temporal memory for LLM applications. Enable your AI to remember across conversations with intelligent scoping and versioning.;

Headings (most frequently used words):

memory, backends, persistent, quick, start, how, it, works, hierarchical, scoping, categories, api, temporal, versioning, provider, compatibility, performance, embedder, storage, on, this, page,

Text of the page (most frequently used words):
#memory (43), openai (19), user (17), the (16), from (14), client (13), with_memory (12), for (11), works (10), and (10), context (9), response (9), user_id (9), import (9), headroom (9), session (9), search (8), content (8), memories (8), compression (8), alice (7), all (6), current (6), api (5), messages (5), with (5), llm (5), embeddings (5), memoryconfig (5), text (5), await (5), create (5), stats (5), role (5), chat (5), persistent (5), storage (4), backends (4), temporal (4), this (4), agent (4), cache (4), local (4), groq (4), config (4), embedderbackend (4), anthropic (4), new (4), fact (4), category (4), python (4), gpt (4), model (4), completions (4), performance (3), versioning (3), categories (3), hierarchical (3), scoping (3), how (3), when (3), management (3), that (3), hnsw (3), inline (3), tokens (3), extraction (3), latency (3), uses (3), full (3), embedder_model (3), embedder_backend (3), server (3), now (3), chain (3), get (3), only (3), add (3), history (3), print (3), prefer (3), preference (3), morning (3), across (3), use (3), extra (3), them (3), conversation (3), sdk (3), provider (2), compatibility (2), embedder (2), quick (2), start (2), sharedcontext (2), intelligent (2), importance (2), sqlite (2), fts5 (2), part (2), 100 (2), your (2), azure (2), true (2), vector (2), ollama (2), made (2), decisions (2), is_current (2), google (2), false (2), query (2), orig (2), supersede (2), memorycategory (2), hierarchicalmemory (2), facts (2), total (2), clear (2), senior (2), engineer (2), results (2), preferences (2), semantic (2), wrapper (2), working (2), identity (2), likes (2), what (2), language (2), client2 (2), afternoon (2), session_id (2), bob (2), persists (2), sessions (2), code (2), client1 (2), turn (2), scope (2), block (2), index (2), call (2), relevant (2), every (2), extracted (2), zero (2), limitations (2), architecture (2), reference (2), configuration (2), proxy (2), reversible (2), page, compressed, inter, sharing, reduce, token, usage, agents, hand, off, each, other, based, scores, learned, patterns, rolling, window, fallback, output, buffer, reservation, lru, lookup, 1ms, hit, indexing, 10ms, 50ms, injection, notes, operation, https, resource, com, base_url, any, compatible, 1000, cache_max_size, cache_enabled, hnsw_ef_search, hnsw_m, 200, hnsw_ef_construction, 384, vector_dimension, db_path, crud, filtering, similarity, keyword, embedded, external, services, required, nomic, embed, http, localhost, 11434, ollama_base_url, many, models, embedding, small, openai_api_key, higher, quality, costs, money, minilm, recommended, fast, free, private, gives, you, audit, trail, ability, debug, why, certain, rollback, needed, get_history, returns, include_superseded, memoryfilter, state, excludes, superseded, default, new_content, old_memory_id, changes, jobs, old, original, change, creates, preserves, supersession, get_all, all_memories, manually, top_k, exposes, attribute, direct, access, tends, typed, languages, derived, insights, insight, chose, postgresql, over, mysql, decision, project, apollo, react, team, lead, sarah, information, about, entities, entity, migrating, microservices, auth, goals, ongoing, tasks, fintech, startup, constraints, prefers, dark, mode, dislikes, preferred, approaches, examples, description, are, categorized, better, organization, retrieval, recalls, microservice, different, same, stored, level, critical, ephemeral, single, specific, task, long, term, time, case, exist, four, levels, broadest, narrowest, happens, calls, cleans, strips, before, returning, return, saves, store, extracts, parse, forwards, request, adds, instruction, system, prompt, instruct, finds, prepends, message, inject, intercepts, completion, should, later, backend, work, exactly, like, normal, one, line, instead, carrying, 000, carry, llms, have, two, fundamental, windows, overflow, too, much, starts, solves, both, extracting, key, persisting, injecting, open, copy, markdown, applications, enable, remember, conversations, troubleshooting, error, handling, help, benchmarks, simulation, metrics, monitoring, observability, mcp, tools, litellm, strands, agno, langchain, vercel, integrations, failure, learning, optimization, ccr, log, image, smartcrusher, community, savings, installation, quickstart, introduction, getting, started,

Text of the page (random words):
persistent memory headroom headroom headroom search k getting started introduction quickstart installation community savings compression how compression works smartcrusher code compression image compression text log compression reversible compression reversible compression ccr cache context cache optimization context management memory persistent memory sharedcontext failure learning proxy server proxy server integrations vercel ai sdk openai sdk anthropic sdk langchain agno strands litellm mcp tools configuration configuration observability metrics monitoring simulation api reference api reference architecture architecture benchmarks limitations help error handling troubleshooting persistent memory persistent memory hierarchical temporal memory for llm applications enable your ai to remember across conversations with intelligent scoping and versioning copy markdown open llms have two fundamental limitations context windows overflow with too much history and every conversation starts from zero persistent memory solves both by extracting key facts persisting them and injecting them when relevant this is temporal compression instead of carrying 10 000 tokens of conversation history carry 100 tokens of extracted memories quick start from openai import openai from headroom import with_memory one line that s it client with_memory openai user_id alice use exactly like normal response client chat completions create model gpt 4o messages role user content i prefer python for backend work memory extracted inline zero extra latency later in a new conversation response client chat completions create model gpt 4o messages role user content what language should i use response uses the python preference from memory how it works the with_memory wrapper intercepts every chat completion call inject semantic search finds relevant memories and prepends them to the user message instruct adds a memory extraction instruction to the system prompt call forwards the request to the llm parse extracts the memory block from the response store saves with embeddings vector index and full text search index return cleans the response strips the memory block before returning memory extraction happens inline as part of the llm response no extra api calls no extra latency hierarchical scoping memories exist at four scope levels from broadest to narrowest scope persists across use case user all sessions all time long term preferences identity session current session only current task context agent current agent in session agent specific context turn single turn only ephemeral working memory from openai import openai from headroom import with_memory session 1 morning client1 with_memory openai user_id bob session_id morning session response client1 chat completions create model gpt 4o messages role user content i prefer go for performance critical code memory stored at user level persists across sessions session 2 afternoon different session same user client2 with_memory openai user_id bob session_id afternoon session response client2 chat completions create model gpt 4o messages role user content what language for my new microservice recalls go preference from morning session memory categories memories are categorized for better organization and retrieval category description examples preference likes dislikes preferred approaches prefers python likes dark mode fact identity role constraints works at fintech startup senior engineer context current goals ongoing tasks migrating to microservices working on auth entity information about entities project apollo uses react team lead is sarah decision decisions made chose postgresql over mysql insight derived insights user tends to prefer typed languages memory api the with_memory wrapper exposes a memory attribute for direct access client with_memory openai user_id alice search memories semantic results client memory search python preferences top_k 5 for memory in results print f memory content add a memory manually client memory add user is a senior engineer category fact importance 0 9 get all memories for this user all_memories client memory get_all clear all memories client memory clear get stats stats client memory stats print f total memories stats total print f by category stats categories temporal versioning when facts change headroom creates a supersession chain that preserves history from headroom memory import hierarchicalmemory memorycategory memory await hierarchicalmemory create original fact orig await memory add content user works at google user_id alice category memorycategory fact user changes jobs supersede the old memory new await memory supersede old_memory_id orig id new_content user now works at anthropic query current state excludes superseded by default current await memory query memoryfilter user_id alice include_superseded false returns only user now works at anthropic get the full chain chain await memory get_history new id memory content user works at google is_current false memory content user now works at anthropic is_current true this gives you an audit trail the ability to debug why the llm made certain decisions and rollback if needed backends embedder backends from headroom memory import memoryconfig embedderbackend local embeddings recommended fast free private config memoryconfig embedder_backend embedderbackend local embedder_model all minilm l6 v2 openai embeddings higher quality costs money config memoryconfig embedder_backend embedderbackend openai openai_api_key sk embedder_model text embedding 3 small ollama embeddings local server many models config memoryconfig embedder_backend embedderbackend ollama ollama_base_url http localhost 11434 embedder_model nomic embed text storage storage uses sqlite for crud and filtering hnsw for vector similarity search and fts5 for full text keyword search all embedded no external services required config memoryconfig db_path memory db vector_dimension 384 hnsw_ef_construction 200 hnsw_m 16 hnsw_ef_search 50 cache_enabled true cache_max_size 1000 provider compatibility memory works with any openai compatible client from openai import openai from headroom import with_memory openai client with_memory openai user_id alice azure openai client with_memory openai base_url https your resource openai azure com user_id alice groq from groq import groq client with_memory groq user_id alice performance operation latency notes memory injection 50ms local embeddings hnsw search memory extraction 50 100 tokens part of llm response inline memory storage 10ms sqlite hnsw fts5 indexing cache hit 1ms lru cache lookup context management intelligent importance based context management that scores messages by learned patterns with rolling window fallback and output buffer reservation sharedcontext compressed inter agent context sharing reduce token usage by 80 when agents hand off to each other on this page quick start how it works hierarchical scoping memory categories memory api temporal versioning backends embedder backends storage provider compatibility performance