v0.2.1 Released

Cognitive Memory
for AI Agents.

A beautiful, unified Python library for giving your LLMs durable, long-term memory. It actively reflects on conversations, extracts emotional valences, maps semantic graphs, and intelligently injects context.

pip install gistlattice

Quick Start

GistLattice defaults to fast, in-memory databases and synchronous APIs. You can start prototyping immediately without spinning up infrastructure. Just bring an API key (like OPENAI_API_KEY).

from gistlattice import GistLattice

def main():
    # 1. Initialize the client
    memory = GistLattice(provider="openai", tenant_id="demo", user_id="user-123")

    # 2. Store an interaction (auto-buffers in memory to save LLM calls)
    memory.remember(
        prompt="I'm feeling stressed about the product launch tomorrow.",
        response="I understand. Let's review the final checklist to be ready."
    )
    print("Memory buffered!")

    # 3. Retrieve formatted context to inject into your next LLM prompt
    context = memory.hydrate_context("What should I do next?")
    
    print(context)

if __name__ == "__main__":
    main()

How it Works: A Human Example

Most "Agent Memory" systems simply dump raw chat transcripts into a vector database. GistLattice uses an LLM to actively reflect on a conversation, extracting the Gist, the Valence (emotion), and the Importance.

1. The Buffer

GistLattice intercepts conversations and buffers them in short-term memory (detecting topic shifts dynamically). It prevents making expensive DB/LLM calls on every single message.

2. The Reflection

Once flushed, it uses an LLM to analyze the buffer. Passing comments decay quickly; major life events (Importance > 0.8) are cemented permanently.

The Story of Sarah & Nexus

Day 1: The Major Life Event

I just got hired at Acme Corp and I'm moving to New York next month! I'm honestly incredibly stressed about finding an apartment.

Congratulations on Acme Corp! Finding an apartment in New York is tough, but we can break it down step-by-step. Don't stress, I'll help you.

Behind the scenes: GistLattice extracts:
Gist: "Hired at Acme Corp, moving to NY, needs apartment"
Importance: 0.9 (Major event)
Valence: -0.7 (Stressed/Anxious)
Semantic Updates: LOCATED_AT "New York"

Six Months Later... The Short-Term Buffer is wiped.

I'm exhausted from work today. Any ideas for what I should do for dinner?

hydrate_context() injects:
[SYSTEM CONTEXT: The user is Sarah. Her current location is New York. She is employed at Acme Corp. Past memory: She was very stressed about moving here 6 months ago.]

Rough day at Acme Corp? Since you're in New York, you should treat yourself. There's a fantastic Italian place two blocks from your office. You survived the stressful move, you deserve a break!

Sarah is blown away. She hasn't mentioned Acme Corp or New York in six months, but her AI remembered her exact life situation.

The Core API

The entire surface area of the library is encapsulated in three methods.

1. `remember()` and `aremember()`

Takes a user prompt and an agent response, buffers them, and saves the structured memory to the database once a conversational limit or topic-shift is reached.

Parameter	Type	Description
`prompt` Required	`str`	The message the user sent.
`response` Required	`str`	The message the AI agent replied with.
`run_in_background` Optional	`bool`	If `True`, pushes the job to the Queue broker immediately.
`bypass_buffer` Optional	`bool`	If `True`, skips the MemoryBufferController and forces an immediate LLM analysis.

2. `hydrate_context()` and `ahydrate_context()`

Searches the unified storage backend for memories relevant to the upcoming prompt, and formats them into a perfectly constructed "System Prompt" block.

upcoming_query = "What should I focus on today?"
system_prompt_addition = memory.hydrate_context(upcoming_query)

final_prompt = f"{system_prompt_addition}\n\nUser: {upcoming_query}"

3. `retrieve()` and `aretrieve()`

Fetches the raw structured memory objects if you prefer to build your own custom system prompt.

Async Processing & Queues

For high-traffic applications (like FastAPI), you do not want to block your user's web request waiting for an LLM to analyze a memory. You can queue the task asynchronously.

⚡

High Performance Setup

Set queue_backend="redis" and use aremember(run_in_background=True) to instantly drop the workload onto a Redis queue. A separate worker process consumes it!

🌐

Distributed Short-Term Buffer

When you enable Redis, GistLattice automatically upgrades your short-term conversational buffer from local Python memory to a distributed Redis store. This allows you to scale multiple web-workers horizontally while perfectly maintaining conversation continuity!

Production Backends

When you are ready to persist your AI's memories durably, connect GistLattice to scalable storage backends by installing the extras:

pip install gistlattice[postgres,neo4j,redis]

PostgreSQL (pgvector)

GistLattice unifies episodic vectors and semantic graphs into relational bridge tables in Postgres via asyncpg and pgvector (HNSW).

storage_backend="postgres"

Neo4j

Maintains a literal living knowledge graph of concepts while utilizing native vector indices for similarity retrieval.

storage_backend="neo4j"

Supported LLM Providers

GistLattice ships with built-in support for the four major LLM providers. Switching is as simple as changing the provider="gemini" string.

Provider	Extras Install	API Key Env Var	Notes
OpenAI	`[openai]`	`OPENAI_API_KEY`	Default provider. Supports chat & embeddings.
Gemini	`[gemini]`	`GEMINI_API_KEY`	Highly recommended for cost-effective analysis.
Anthropic	`[anthropic,openai]`	`ANTHROPIC_API_KEY`	Requires a separate `embedding_provider` (e.g. openai) as Anthropic lacks a public embedding API.
Ollama	`[ollama]`	None (Local)	Requires local daemon running. Specify `llm_model` and `embedding_model` explicitly.

Client Initialization (Kwargs)

The GistLattice class accepts extensive keyword arguments to configure underlying behavior, overriding any set environment variables.

Parameter	Type	Description & Default
`provider` Optional	`str`	LLM provider (`openai`, `gemini`, `anthropic`, `ollama`). Default: `openai`.
`tenant_id` Optional	`str`	Organization ID for multi-tenant isolation. Default: `default`.
`user_id` Optional	`str`	User ID for multi-tenant isolation. Default: `default`.
`app_name` Optional	`str`	Default: `GistLattice`.
`environment` Optional	`str`	Default: `development`.
`llm_model` Optional	`str`	Overrides the default chat model.
`embedding_provider` Optional	`str`	Separate provider for embeddings. Defaults to `provider`.
`embedding_model` Optional	`str`	Overrides the default embedding model.
`llm_factory_path` Optional	`str`	Path to a custom LLM factory Python object.
`storage_backend` Optional	`str`	Unified storage (`memory`, `postgres`, `neo4j`). Default: `memory`.
`queue_backend` Optional	`str`	Job queue (`memory` or `redis`). Default: `memory`.
`postgres_url` Optional	`str`	Default: `postgresql://user:password@localhost:5432/gistlattice`.
`neo4j_uri` Optional	`str`	Default: `bolt://localhost:7687`.
`neo4j_username` Optional	`str`	Default: `neo4j`.
`neo4j_password` Optional	`str`	Default: `password`.
`redis_url` Optional	`str`	Default: `redis://localhost:6379/0`.
`redis_queue_name` Optional	`str`	Default: `memory-consolidation`.
`redis_processing_name` Optional	`str`	Default: `memory-consolidation:processing`.
`memory_limit` Optional	`int`	Number of memories retrieved per query. Default: `3`.
`buffer_size` Optional	`int`	Number of interactions held in the short-term sliding window. Default: `15`.
`use_semantic_buffer` Optional	`bool`	If True, detects topic shifts using embeddings to dynamically flush the buffer. Default: `False`.

Environment Variables

Define your settings globally in a .env file. The client automatically absorbs them.

Environment Variable	Description / Default
`GISTLATTICE_APP_NAME`	Default: `GistLattice`.
`GISTLATTICE_ENV`	Default: `development`.
`GISTLATTICE_LLM_PROVIDER`	Default LLM (`openai`, `gemini`, `anthropic`, `ollama`).
`GISTLATTICE_LLM_MODEL`	Overrides the default chat model.
`GISTLATTICE_EMBEDDING_PROVIDER`	Separate provider for embeddings. Defaults to `LLM_PROVIDER`.
`GISTLATTICE_EMBEDDING_MODEL`	Overrides the default embedding model.
`GISTLATTICE_LLM_FACTORY_PATH`	Path to a custom LLM factory Python object.
`GISTLATTICE_STORAGE_BACKEND`	Unified storage (`memory`, `postgres`, `neo4j`). Default: `memory`.
`GISTLATTICE_QUEUE_BACKEND`	Job queue (`memory` or `redis`). Default: `memory`.
`GISTLATTICE_POSTGRES_URL`	`postgresql://user:password@localhost:5432/gistlattice`
`GISTLATTICE_NEO4J_URI`	`bolt://localhost:7687`
`GISTLATTICE_NEO4J_USERNAME`	`neo4j`
`GISTLATTICE_NEO4J_PASSWORD`	`password`
`GISTLATTICE_REDIS_URL`	`redis://localhost:6379/0`
`GISTLATTICE_REDIS_QUEUE_NAME`	`memory-consolidation`
`GISTLATTICE_REDIS_PROCESSING_NAME`	`memory-consolidation:processing`
`GISTLATTICE_MEMORY_LIMIT`	Number of memories retrieved per query. Default: `3`.
`GISTLATTICE_BUFFER_SIZE`	Number of interactions held in the short-term sliding window. Default: `15`.
`GISTLATTICE_USE_SEMANTIC_BUFFER`	If True, detects topic shifts using embeddings to dynamically flush the buffer. Default: `False`.

Cognitive Memory for AI Agents.

Quick Start

How it Works: A Human Example

1. The Buffer

2. The Reflection

The Story of Sarah & Nexus

The Core API

1. remember() and aremember()

2. hydrate_context() and ahydrate_context()

3. retrieve() and aretrieve()

Async Processing & Queues

Production Backends

PostgreSQL (pgvector)

Neo4j

Supported LLM Providers

Client Initialization (Kwargs)

Environment Variables

Cognitive Memory
for AI Agents.

1. `remember()` and `aremember()`

2. `hydrate_context()` and `ahydrate_context()`

3. `retrieve()` and `aretrieve()`