GistLattice Documentation

Cognitive Memory for AI Agents.

GistLattice is an elegant, three-method Python library for retrieval, hydration, and consolidation of long-lived memory. It analyzes conversations, extracts emotional valences, and intelligently injects context into your LLM prompts.

Quick Start Client Setup Core API Environment Variables

Provider-Agnostic Synchronous & Async Queues Semantic Graph Episodic Vectors

Quick Start

GistLattice defaults to in-memory databases, meaning you can start prototyping immediately without spinning up Redis, Neo4j, or Qdrant. All you need is an API key for your LLM (like OPENAI_API_KEY).

import asyncio
from gistlattice import GistLattice

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

    # 2. Save an interaction synchronously
    analysis = await memory.remember(
        prompt="Help me plan my next task.",
        response="I've added the Paris trip to your agenda."
    )
    print("Memory Saved:", analysis.gist)

    # 3. Inject context into your next prompt
    context = await memory.hydrate_context("What should I do next?")
    print(context)

asyncio.run(main())

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`	The organization ID for multi-tenant isolation. Default: `default`.
`user_id` Optional	`str`	The ID of the specific user. Default: `default`.
`llm_model` Optional	`str`	Override default chat model (e.g., `gpt-4o`). Default: Varies by provider.
`embedding_provider` Optional	`str`	Override the embedding provider (e.g., use `gemini` for embeddings and `openai` for chat). Default: Matches `provider`.
`embedding_model` Optional	`str`	Override default embedding model. Default: Varies by provider.
`episodic_store_backend` Optional	`str`	Episodic vector memory (`memory` or `qdrant`). Default: `memory`.
`semantic_store_backend` Optional	`str`	Semantic graph memory (`memory` or `neo4j`). Default: `memory`.
`queue_backend` Optional	`str`	Background job queue (`memory` or `redis`). Default: `memory`.
`qdrant_host` Optional	`str`	Default: `localhost`.
`qdrant_port` Optional	`int`	Default: `6333`.
`qdrant_collection` Optional	`str`	Default: `user_episodic_stream`.
`qdrant_vector_size` Optional	`int`	Manually set Qdrant vector size. Default: Auto-detected.
`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`	Default number of memories retrieved per query. Default: `3`.

The 3 Core Methods

1. `remember()`

Takes a recent conversation, hands it to an LLM for psychological and semantic reflection, and stores the resulting structured memory durably.

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 a queue (like Redis) and immediately returns a Job ID. If `False` (default), processes synchronously and returns a `MemoryAnalysis` object.

2. `hydrate_context()`

Searches the database for memories relevant to the upcoming prompt, and formats them into a perfectly constructed "System Prompt" string that you can inject into your LLM.

Parameter	Type	Description
`prompt` Required	`str`	The upcoming query the user is about to ask. GistLattice uses this to find the most semantically relevant past memories.

3. `retrieve()`

Fetches the raw structured memory objects. Use this instead of hydrate_context if you want to write your own custom prompt formatter.

Parameter	Type	Description
`query` Required	`str`	The search string used to find relevant vector embeddings.
`limit` Optional	`int`	The maximum number of memories to return. Defaults to `memory_limit` setting (which defaults to 3).

Async Queue Processing (Background Workers)

For high-traffic applications, 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 so it executes in the background.

import asyncio
from gistlattice import GistLattice

async def main():
    # Configure with Redis for distributed background tasks
    memory = GistLattice(
        provider="openai", 
        queue_backend="redis", 
        redis_url="redis://localhost:6379"
    )

    # By setting run_in_background=True, the system instantly queues the 
    # memory and returns a Job ID string instead of a MemoryAnalysis object.
    job_id = await memory.remember(
        prompt="I feel really overwhelmed with this project.",
        response="Let's break it down into smaller steps.",
        run_in_background=True
    )
    
    print(f"Instantly queued job: {job_id}")
    # The user's web request completes instantly.
    # A separate worker process consumes the job and saves it to the database!

asyncio.run(main())

Environment Variables

Instead of passing configuration programmatically into GistLattice(redis_url="..."), you can define them in your environment or a .env file. Environment variables act as the global defaults across your app.

Precedence Rules If you explicitly pass a keyword argument to GistLattice(llm_model="gpt-4"), it will override the environment variable completely.

Environment Variable	Description & Default
`GISTLATTICE_ENV`	Runtime environment. 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_EPISODIC_BACKEND`	Vector storage (`memory` or `qdrant`). Default: `memory`.
`GISTLATTICE_SEMANTIC_BACKEND`	Graph storage (`memory` or `neo4j`). Default: `memory`.
`GISTLATTICE_QUEUE_BACKEND`	Job queue (`memory` or `redis`). Default: `memory`.
`GISTLATTICE_QDRANT_HOST`	Default: `localhost`.
`GISTLATTICE_QDRANT_PORT`	Default: `6333`.
`GISTLATTICE_QDRANT_COLLECTION`	Default: `user_episodic_stream`.
`GISTLATTICE_QDRANT_VECTOR_SIZE`	Manually set dimension size.
`GISTLATTICE_NEO4J_URI`	Default: `bolt://localhost:7687`.
`GISTLATTICE_NEO4J_USERNAME`	Default: `neo4j`.
`GISTLATTICE_NEO4J_PASSWORD`	Default: `password`.
`GISTLATTICE_REDIS_URL`	Default: `redis://localhost:6379/0`.
`GISTLATTICE_REDIS_QUEUE_NAME`	Default: `memory-consolidation`.
`GISTLATTICE_REDIS_PROCESSING_NAME`	Default: `memory-consolidation:processing`.
`GISTLATTICE_MEMORY_LIMIT`	Number of memories retrieved per query. Default: `3`.

Moving to Production Databases

When you are ready to scale, simply install the required extras and update your parameters. The API remains exactly the same.

pip install gistlattice[qdrant,neo4j,redis]

Then configure the client:

memory = GistLattice(
    # Core
    provider="openai",
    
    # Backends
    episodic_store_backend="qdrant",
    semantic_store_backend="neo4j",
    queue_backend="redis",
    
    # Auth
    qdrant_host="localhost",
    neo4j_uri="bolt://localhost:7687",
    neo4j_password="secure_password",
    redis_url="redis://localhost:6379"
)

Cognitive Memory for AI Agents.

Quick Start

Client Initialization (Kwargs)

The 3 Core Methods

1. remember()

2. hydrate_context()

3. retrieve()

Async Queue Processing (Background Workers)

Environment Variables

Moving to Production Databases

1. `remember()`

2. `hydrate_context()`

3. `retrieve()`