Metadata-Version: 2.4
Name: tripartite-memory
Version: 0.1.0
Summary: The Tripartite Memory SDK for Autonomous AI Agents. Unify State, Semantic, and Graph memory.
Author-email: LavaLabs <founders@lavalabs.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/lavalabs/aegis-memory
Project-URL: Documentation, https://github.com/lavalabs/aegis-memory#readme
Project-URL: Repository, https://github.com/lavalabs/aegis-memory.git
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.5.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: psycopg[binary]>=3.1.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: neo4j>=5.14.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: cyclonedx-bom>=4.0.0
Requires-Dist: python-dotenv>=1.0.1

# aegis-memory 🧠
**Stop AI agents from repeating the same mistakes.**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/)

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

```bash
pip install aegis-memory
```

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

```python
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](./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](./examples/bridge.py) that works on Linux, Mac, and Windows.

```bash
# 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`:
```ini
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](./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.
