GibsonAI/memori: Structured Memory Infrastructure for Production AI Agents

GibsonAI/memori: Structured Memory Infrastructure for Production AI Agents

AI agents forget everything between sessions. Developers building production systems have accepted this as inevitable—either paying for ever-larger context windows or accepting that each interaction starts from zero. GibsonAI/memori challenges that assumption with an approach grounded in how agents actually work, not just how they converse. With 15,590 GitHub stars and 2,835 forks, this Python^{↗ Bright Coding Blog}-based open-source project has gained significant traction among engineers who need memory that persists, structures, and scales without ripping out existing infrastructure.

What is GibsonAI/memori?

Memori is agent-native memory infrastructure—an LLM-agnostic layer that transforms agent execution and conversation into structured, persistent state for production systems. Maintained by GibsonAI (formerly MemoriLabs), the project sits between your existing LLM providers and data infrastructure, capturing what happens during agent execution rather than merely logging chat transcripts.

The project's core thesis: memory should derive from what agents do, not just what they say. This distinction matters because modern agents make tool calls, execute multi-step workflows, and produce intermediate decisions that standard conversation logging misses entirely. Memori captures this execution context and structures it into retrievable state.

Key technical characteristics from the repository:

• LLM-agnostic: Works across Anthropic, Bedrock, DeepSeek, Gemini, Grok (xAI), and OpenAI (including both Chat Completions and Responses APIs), supporting streamed, unstreamed, synchronous, and asynchronous modes
• Datastore-agnostic: Integrates with existing data infrastructure without requiring migration or replacement
• Framework integrations: Native support for Agno, LangChain, and Pydantic AI
• Deployment flexibility: Managed cloud, single-tenant cloud, VPC, and on-premises options
• License: Apache 2.0

The project's momentum—15,590 stars with active development through June 2026—suggests it has found product-market fit among teams building serious agent systems rather than prototypes.

Key Features

Structured Memory from Execution, Not Just Conversation

Memori's distinguishing capability is capturing agent execution context—tool calls, decisions, outcomes—rather than merely persisting chat messages. This produces richer retrieval context when agents need to recall prior interactions.

Multi-Level Attribution System

Memori tracks memories across three hierarchical levels:

• Entity: The actor (user, organization, or object)
• Process: The specific agent, workflow, or program
• Session: The bounded interaction between entity and process

This granularity enables precise context retrieval without leaking unrelated conversation history.

Advanced Augmentation (Background Enrichment)

Memori automatically enriches captured memories with derived attributes: events, facts, people references, preferences, relationships, rules, and skills. This augmentation runs asynchronously—no latency penalty on the critical path. The free tier includes rate-limited access; production workloads require signup.

Benchmark-Validated Efficiency

On the LoCoMo long-conversation memory benchmark, Memori achieved 81.95% overall accuracy using only 1,294 tokens per query—4.97% of full-context footprint. Compared to retrieval-based alternatives, this represents roughly 67% reduction versus Zep and over 20x context cost reduction versus naive full-context prompting.

Multiple Integration Patterns

The project supports varied adoption paths: direct SDK integration, OpenClaw gateway plugin, Hermes Agent memory provider, and MCP (Model Context Protocol) server for tools like Claude Code, Cursor, Codex, Warp, and Antigravity.

Use Cases

Long-Running Customer Support Agents

Support agents that maintain context across ticket reopenings, escalations, and channel switches. Memori's entity-level attribution ensures a user's preferences and history persist even when different agent processes handle subsequent interactions.

Multi-Step Workflow Automation

Agents executing complex business processes—loan underwriting, claims processing, procurement—generate substantial intermediate state. Memori captures tool call outcomes and decisions, enabling resumption and audit without reconstructing from logs.

Team-Shared Development Context

The MCP integration enables coding assistants to accumulate project conventions, reviewer preferences, and architectural decisions. New team members inherit this context through the agent rather than months of tribal knowledge absorption.

Compliance-Sensitive Deployments

Single-tenant cloud, VPC, and on-premises deployment options satisfy data residency requirements that preclude managed AI services. The BYODB (Bring Your Own Database) path integrates with existing TiDB or other supported stores.

Cost-Optimized High-Volume Agents

Teams running agents at scale benefit from the LoCoMo-demonstrated token efficiency. Reducing per-query context by 20x translates directly to lower inference costs without accuracy degradation.

Installation & Setup

Memori provides SDKs for both TypeScript and Python environments.

TypeScript SDK

npm install @memorilabs/memori

Python SDK

pip install memori

API Key Configuration

Sign up at app.memorilabs.ai to obtain a Memori API key. Set this as an environment variable alongside your LLM provider key:

export MEMORI_API_KEY=your_memori_key
export OPENAI_API_KEY=your_openai_key  # or equivalent for other providers

The Memori CLI (installed with the Python package) uses exported environment variables first, then falls back to a .env file in the working directory.

Optional: Memori CLI Installation

The CLI manages accounts, keys, and quotas:

python -m memori

For BYODB deployments, consult the Memori BYODB documentation. For disposable development databases, TiDB Zero provisioning is documented at docs/memori-byodb/databases/tidb.mdx in the repository.

Real Code Examples

Basic Python Integration with OpenAI

This example demonstrates the minimal integration pattern: register your existing OpenAI client with Memori, provide attribution, and memory persistence operates automatically.

from memori import Memori
from openai import OpenAI

# Requires MEMORI_API_KEY and OPENAI_API_KEY in your environment
client = OpenAI()
mem = Memori().llm.register(client)

mem.attribution(entity_id="user_123", process_id="support_agent")

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "My favorite color is blue."}]
)
# Conversations are persisted and recalled automatically.

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What's my favorite color?"}]
)
# Memori recalls that your favorite color is blue.

The attribution call is mandatory—without entity and process identifiers, Memori cannot create memories. The .llm.register(client) pattern wraps the existing client without requiring proxy objects or request interception.

TypeScript Equivalent

import { OpenAI } from 'openai';
import { Memori } from '@memorilabs/memori';

// Requires MEMORI_API_KEY and OPENAI_API_KEY in your environment
const client = new OpenAI();
const mem = new Memori().llm
  .register(client)
  .attribution('user_123', 'support_agent');

async function main() {
  await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'My favorite color is blue.' }],
  });
  // Conversations are persisted and recalled automatically in the background.

  const response = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: "What's my favorite color?" }],
  });
  // Memori recalls that your favorite color is blue.
}

MCP Server Configuration (Claude Code)

For MCP-compatible tools, no SDK integration is required. The server exposes Memori's capabilities via the Model Context Protocol:

claude mcp add --transport http memori https://api.memorilabs.ai/mcp/ \
  --header "X-Memori-API-Key: ${MEMORI_API_KEY}" \
  --header "X-Memori-Entity-Id: your_username" \
  --header "X-Memori-Process-Id: claude-code"

Cursor, Codex, Warp, and Antigravity configurations follow similar patterns; see the MCP client setup guide in the repository.

OpenClaw Gateway Plugin

For OpenClaw deployments, installation requires no agent code changes:

openclaw plugins install @memorilabs/openclaw-memori
openclaw plugins enable openclaw-memori

openclaw memori init \
  --api-key "YOUR_MEMORI_API_KEY" \
  --entity-id "your-app-user-id" \
  --project-id "my-project"

openclaw gateway restart

The plugin hooks into OpenClaw's lifecycle to capture structured memory after each turn, including tool calls and execution outcomes.

Advanced Usage & Best Practices

Session Management for Multi-Step Agents

By default, Memori manages session boundaries automatically. For agents with explicit workflow phases, manual control may improve memory organization:

mem.new_session()      # Start fresh session
# or
mem.set_session(session_id)  # Resume specific session

In TypeScript: mem.resetSession() or mem.setSession(sessionId).

Attribution Design

The entity/process distinction enables flexible scoping. Consider:

• Entity = organization ID for B2B tools where organizational memory matters more than individual
• Process = specific workflow variant (e.g., "onboarding_v2" vs "onboarding_v3") to isolate experimental agent versions
• Multiple processes per entity when users interact with distinct agent specializations

Quota Monitoring

Check consumption via CLI:

python -m memori quota

Or through the web dashboard at app.memorilabs.ai. The free tier applies IP-based rate limiting; API key authentication removes this restriction.

Performance Considerations

The LoCoMo benchmark demonstrates that structured memory retrieval maintains accuracy with dramatically smaller prompts. However, this efficiency assumes proper attribution—unattributed interactions create orphaned memory fragments that consume storage without improving retrieval.

Comparison with Alternatives

Memori's execution-level memory capture and deployment flexibility distinguish it, though teams with simple chatbot requirements may find Zep or Mem0 sufficient. The benchmark claims should be validated independently for your specific use case.

FAQ

Is GibsonAI/memori free to use?

The core SDK and basic memory features are free with rate limits. Advanced Augmentation and production quotas require signup. BYODB deployments use your own infrastructure costs.

What databases does BYODB support?

The README explicitly documents TiDB; other datastores may be supported—consult the Memori BYODB documentation for current options.

Can I use Memori with async OpenAI clients?

Yes—all SDK methods support synchronous and asynchronous execution, plus streamed and unstreamed responses.

How does attribution affect privacy?

Memories are scoped to entity-process pairs. Without attribution, no memory is created—this is a safety feature, not a bug.

Is the project actively maintained?

Last commit dated June 15, 2026, with 15,590 stars indicating substantial community engagement.

What's the difference between Memori Cloud and BYODB?

Cloud offers zero-configuration managed service; BYODB connects to your existing database infrastructure for data residency or cost control.

Does Memori work with self-hosted LLMs?

The README lists specific providers (Anthropic, Bedrock, DeepSeek, Gemini, Grok, OpenAI). Custom endpoint support is not explicitly documented.

Conclusion

GibsonAI/memori addresses a genuine gap in the agent infrastructure landscape: memory that captures execution context, not just conversation transcripts. For teams building production agents—particularly multi-step workflows, long-running customer interactions, or compliance-sensitive deployments—its structured approach and deployment flexibility merit evaluation.

The project's benchmark results suggest meaningful cost reductions through efficient context retrieval, though independent verification is advisable. The Apache 2.0 license and active development reduce adoption risk for organizations cautious about vendor lock-in.

If your agents currently start each session from zero, or you're paying premium context window costs to maintain continuity, explore GibsonAI/memori on GitHub and test against your specific workload patterns.

For related approaches to agent infrastructure, see our coverage of [INTERNAL_LINK: LLM orchestration frameworks] and [INTERNAL_LINK: production AI deployment patterns].