Portable, updatable, truth-preserving memory for agentic AI

SozoGraph turns interaction history into a portable cognitive snapshot you can inject into any AI agent context on the fly.

It answers one question cleanly:

"Given everything that has happened so far, what should an agent currently believe about this user?"

Not:

• what was said
• what is similar
• what might be relevant

But:

• what is true now
• what is stable
• what is unresolved
• what is contradictory (resolved by time)

Most "memory" systems treat memory as text to retrieve, not truth to update:

The result? Agents act like goldfish even when data exists.

It's a truth-layer memory object:

• ✅ Typed — Facts ≠ preferences ≠ entities ≠ open loops
• ✅ Temporal — New updates override old; contradictions are explicit
• ✅ Portable — Lightweight JSON passport + compact context string
• ✅ Deterministic — Same inputs → same memory state

pip install sozograph

📓 Run the Example Notebook — See live demos of ingestion, contradiction tracking, and context export.

from sozograph import SozoGraph

sg = SozoGraph()

# Ingest a transcript
passport, stats = sg.ingest(
    "I'm building AI agents. I prefer direct answers and hate jargon.",
    meta={"user_key": "u_123"}
)

# Export compact context for your agent
briefing = sg.export_context(passport, budget_chars=2500)
print(briefing)

Output:

SOZOGRAPH PASSPORT v1
User: u_123
Updated: 2026-02-04T19:26:00+00:00

Facts (current beliefs):
- role: AI agent development

Preferences:
- communication_style: direct, jargon-free
...

# Agent sees structured beliefs, not raw transcripts
{
  "facts": {"current_project": "sozograph"},
  "preferences": {"tone": "direct"},
  "entities": ["Gemini 3", "PyPI"],
  "open_loops": ["finalize v1 docs"],
  "contradictions": []
}

Why this matters: Agents can update facts without losing preferences, distinguish current state from history, and maintain consistency across sessions.

# Jan 15: "I live in NYC"
# Feb 1: "I moved to SF"

# RAG: Retrieves both → confusion
# SozoGraph: 
{
  "facts": {"location": "SF"},
  "contradictions": [{
    "key": "location",
    "old_value": "NYC",
    "new_value": "SF", 
    "changed_at": "2026-02-01"
  }]
}

Because passports are lightweight JSON, they work everywhere:

• Stateless clients (ElevenLabs WebSocket, voice agents)
• Server-side orchestrators (LangChain, AutoGen)
• Edge deployments (Cloudflare Workers, Vercel Edge)

Real-world applications:

• 🏥 Health & Fitness — Remember dietary restrictions, workout progressions
• 📚 Education — Track learning weaknesses, adapt assessments
• 🛍️ Shopping — Recall style preferences, purchase history
• 💬 Support — Maintain context across channels

Create a .env file:

GEMINI_API_KEY=your_key_here
SOZOGRAPH_EXTRACTOR_MODEL=gemini-3-flash-preview
SOZOGRAPH_ENABLE_FALLBACK_SUMMARIZER=true
SOZOGRAPH_MAX_INTERACTION_CHARS=4000
SOZOGRAPH_DEFAULT_CONTEXT_BUDGET=3000

history = [
    {"createdAt": "2026-02-01T10:00:00Z", "transcript": "I'm renovating my kitchen."},
    {"createdAt": "2026-02-02T09:30:00Z", "transcript": "I prefer rustic style."},
    {"createdAt": "2026-02-03T12:10:00Z", "transcript": "Budget is $50k max."},
]

passport, _ = sg.ingest(history)

Firestore:

firestore_doc = {
  "id": "abc123",
  "createdAt": "2026-02-03T10:00:00Z",
  "notes": "User prefers direct answers."
}
passport, _ = sg.ingest(firestore_doc, hint="firestore")

Supabase:

supabase_row = {
  "table": "events",
  "row": {"event": "preference_update", "notes": "Wants code-first approach"}
}
passport, _ = sg.ingest(supabase_row, hint="supabase")

Firebase RTDB:

rtdb_snapshot = {
  "path": "/users/u1/profile",
  "value": {"displayName": "Alice", "preferences": {"tone": "casual"}}
}
passport, _ = sg.ingest(rtdb_snapshot, hint="rtdb")

1. Canonicalize — Coerce inputs into Interaction objects (deterministic)
2. Extract — Gemini 3 Flash reasons about belief updates (strict JSON schema)
3. Resolve — Deterministic merger applies temporal priority, tracks contradictions
4. Export — Compact passport ready for context injection

Key insight: This is belief inference, not keyword extraction. Gemini 3’s reasoning enables distinguishing facts from preferences, detecting implicit updates, and maintaining temporal consistency.

• ❌ Not a graph database
• ❌ Not RAG / embeddings
• ❌ Not a conversation logger
• ❌ Not a DB client (objects-only by design)

SozoGraph is a memory normalization layer that sits before agent planning, tool use, and retrieval.

Measured on 10-turn conversations with 3 belief updates (non-scientific experiment)

• CLI tools (sozograph ingest, sozograph render)
• Enhanced input detection for transcript lists
• Improved JSON recovery for malformed model outputs
• Stronger evidence linking

• Optional graph engine support (Neo4j, Memgraph)
• Cypher-style relational queries
• Temporal edge deprecation
• Active truth subgraph exports

• Multi-model support (OpenAI, Claude, local models)
• MCP tool server integration
• Hybrid graph + vector patterns

We welcome contributions that keep v1 disciplined and portable.

• Adapters for new object shapes (objects-only)
• Resolver logic improvements (deterministic)
• Tests for edge cases (contradictions, merge conflicts)
• Prompt engineering for extraction quality

• RAG/embedding features
• Graph database integrations (wait for v1.5)

1. Fork the repo
2. Create a branch: feat/your-feature
3. Add tests where relevant
4. Open a PR with clear explanation + examples

• Example Notebook — Interactive demos
• Test Fixtures — Sample data for validation
• PyPI Package — Latest release

“We are not helping agents remember more. We are helping them remember correctly.”

SozoGraph enables agents to maintain consistent beliefs across sessions, systems, and model providers—something RAG and chat history cannot provide.

MIT — Sozo Analytics Lab

This project was built for the Gemini 3 Global Hackathon to demonstrate how structured memory normalization unlocks the next generation of agentic AI applications.

Try it now:

pip install sozograph

Questions? Open an issue or check the example notebook.