tripartite-memory 0.1.0

The Tripartite Memory SDK for Autonomous AI Agents. Unify State, Semantic, and Graph memory.

aegis-memory 🧠

Stop AI agents from repeating the same mistakes.

Most LLM agents fail in the same way: they forget what already happened. They retry failed approaches, ignore system state, and confidently suggest things that already broke production.

This is AI Amnesia.

aegis-memory is a unified async Python SDK that gives AI agents persistent, structured memory across three distinct layers. Before an agent takes action, it can answer:

“Has this failed before?”
“What will this impact?”
“Is this safe to execute?”

Instead of guessing, it knows.

Memory & Context Optimization ⚡

aegis-memory significantly reduces the cost and improves the performance of running large models:

• 60-80% Token Reduction: Instead of dumping massive chat histories into the prompt, recall() injects only the 3-5 most relevant precedents.
• VRAM Relief: By keeping context windows lean, models consume less VRAM (which scales quadratically with sequence length). Run larger models (32B/70B) on consumer-grade hardware.
• Improved Reasoning: Providing specific "Hard Constraints" from the Ledger prevents the LLM from making up rules, leading to deterministic and reliable outputs.

What This Fixes

Without memory:

• Agents loop on failed solutions.
• Context windows explode with irrelevant history.
• Risky actions happen without awareness of dependencies.

With aegis-memory:

• Agents avoid known failure paths.
• Context stays small and relevant.
• Actions are informed by real system state and "trace the real blast radius."

The Tripartite Architecture

To make an LLM safe for production, it needs an operating-system-level memory stack:

1. The Ledger (Postgres): Immutable state, strict constraints, and audit logs.
2. The Semantic Engine (Qdrant): High-dimensional vector search for historical precedents and documentation.
3. The Capability Graph (Neo4j): Dependency mapping to understand how modifying Component A impacts System B.

Installation

pip install aegis-memory

Quickstart

Initialize the MemoryCore with your database credentials (or use a .env file).

import asyncio
from tripartite_memory.core import MemoryCore

async def main():
    # Automatically loads from .env
    memory = MemoryCore()

    # 1. Unified Ingestion (Write to all 3 databases simultaneously)
    await memory.ingest(
        content="Modified the Nginx reverse proxy to route /api/v2 traffic to staging.",
        actor="agent:InfrastructureOps",
        tags=["nginx", "networking", "staging"]
    )

    # 2. Pre-Action Context Check (The Blast Radius)
    # Give your agent complete situational awareness before it touches production.
    context = await memory.recall(
        intent="Restart the Nginx service to apply new SSL certificates.",
        graph_depth=2
    )

    print(context.status) # "KNOWN", "ADJACENT", or "UNKNOWN"
    print(context.blast_radius) # Neo4j dependent nodes
    print(context.historical_precedents) # Qdrant vector matches

if __name__ == "__main__":
    asyncio.run(main())

The Agent Protocol 🛡️

aegis-memory works best when the agent is "forced" to use it. We recommend adding a Memory Protocol to your agent's system prompt. See SYSTEM_PROMPT.md for the exact snippet.

Universal Integration

• Local Models (Ollama/LM Studio): Inject the recall() JSON directly into the context window before the user's prompt.
• CLI Clients (Claude Code/Gemini CLI): Wrap the SDK in a tool or use the provided Bridge Script.

Bi-directional Memory Bridge 🔄

We provide a ready-to-use bridge in examples/bridge.py that works on Linux, Mac, and Windows.

# Get Context
python examples/bridge.py recall "How do I optimize VRAM on Pascal?"

# Store Knowledge
python examples/bridge.py ingest "Successfully tuned batch size to 4 for Qwen-32B." --tags optimization

Remote Connection Guide (LAN) 🌐

If testing from a remote machine, point the SDK to your server's IP in your .env:

POSTGRES_URL=postgresql://user:password@10.0.0.100:5432/aegis_local
QDRANT_URL=http://10.0.0.100:6333
NEO4J_URI=bolt://10.0.0.100:7687
NEO4J_PASSWORD=your-secure-password
OLLAMA_URL=http://10.0.0.100:11434

SBOM & Transparency 🛡️

In alignment with AEGIS OS security standards, this repository includes a Software Bill of Materials (SBOM) in CycloneDX format.

• View SBOM: sbom.json
• Generate Fresh SBOM: python scripts/generate_sbom.py

Why We Built This

We built this SDK as the foundational memory layer for AEGIS OS—a bare-metal orchestration layer designed to govern AI agents on real infrastructure using deterministic safety tiers (T0/T1/T2).

While the core OS uses a Business Source License (BSL), we believe fundamental agentic memory should be open and standardized. aegis-memory is 100% open-source (Apache 2.0).

Contributing

PRs are welcome. If you are building agentic systems that require strict intent multiplexing and deterministic safety, we'd love to collaborate. e'd love to collaborate. equire strict intent multiplexing and deterministic safety, we'd love to collaborate.