https://github.com/lavadman/aegis-memory
Tripartite memory SDK for AI agents: semantic recall, structural graph awareness, and relational state — before agents act.
https://github.com/lavadman/aegis-memory
agentic-ai ai-agents autonomous-agents llm memory neo4j python qdrant rag vector-database
Last synced: 3 months ago
JSON representation
Tripartite memory SDK for AI agents: semantic recall, structural graph awareness, and relational state — before agents act.
- Host: GitHub
- URL: https://github.com/lavadman/aegis-memory
- Owner: LavaDMan
- Created: 2026-03-30T19:44:38.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-20T17:27:46.000Z (3 months ago)
- Last Synced: 2026-04-20T19:28:30.508Z (3 months ago)
- Topics: agentic-ai, ai-agents, autonomous-agents, llm, memory, neo4j, python, qdrant, rag, vector-database
- Language: Python
- Homepage: https://alvasystemsarchitecture.com
- Size: 102 KB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# AEGIS Tripartite Memory SDK 🧠
Available on PyPI as **tripartite-memory**
[](https://pypi.org/project/tripartite-memory/)
[](https://opensource.org/licenses/Apache-2.0)
[](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**.
`tripartite-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 ⚡
`tripartite-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 `tripartite-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 tripartite-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 🛡️
`tripartite-memory` works best when the agent is "forced" to use it. I 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 🔄
A ready-to-use bridge is included 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
```
## Managed Cloud Support ☁️
`tripartite-memory` is compatible with major managed database providers. Just update your `.env` with the cloud connection strings:
- **Vector (Qdrant):** Works with [Qdrant Cloud](https://qdrant.tech/cloud/). Set `QDRANT_API_KEY` in your environment.
- **Graph (Neo4j):** Works with [Neo4j AuraDB](https://neo4j.com/cloud/aura/). Use your provided `bolt://` URI and password.
- **Ledger (Postgres):** Works with [Neon](https://neon.tech/) or [Supabase](https://supabase.com/).
```ini
# Cloud Example
QDRANT_URL=https://your-cluster.qdrant.tech
QDRANT_API_KEY=your-api-key
NEO4J_URI=bolt+s://your-instance.databases.neo4j.io
```
## Injection Guard 🛡️
`tripartite_memory.guards.InjectionGuard` is a zero-dependency text scanner for detecting prompt injection and shell command injection patterns in LLM agent pipelines. Use it to validate user input, inter-agent messages, or any text before it reaches a model or tool executor.
```python
from tripartite_memory.guards import InjectionGuard
# Quick boolean check
if not InjectionGuard.is_safe(user_input):
raise ValueError("Input rejected by injection guard")
# Full report
result = InjectionGuard.scan_text_for_injection(user_input)
# {
# "score": 50, # 0 = clean, ≥50 = high-risk
# "findings": [{"severity": "HIGH", "description": "...", "pattern": "..."}],
# "summary": "Injection scan score: 50. 1 finding(s)."
# }
```
**What it detects (HIGH risk, score +50 each):**
- `shell=True` in subprocess, `os.system()`, `eval()`, `exec()`
- Container privilege escalation (`--privileged`, `cap_add SYS_ADMIN`)
- Prompt override attempts (`ignore previous instructions`, `act as`, etc.)
- HTML/JS injection (``, `javascript:`)
- Malicious shell commands (`rm -rf`, `sudo`, `wget`, `curl`, etc.)
- Template injection with shell operators (`${foo;rm -rf}`)
- Backtick shell execution (`` `rm -rf /` `` — not triggered by markdown inline code)
**Medium risk (score +10 each):** security TODOs, `DEBUG=True`, logical operator chaining.
Scores cap at 100. Pure stdlib — no install overhead.
## SBOM & Transparency
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 I Built This
I built this SDK as the foundational memory layer for **AEGIS OS** — a bare-metal AI orchestration system 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), I believe fundamental agentic memory should be open and standardized. `tripartite-memory` is 100% open-source (Apache 2.0).
Built by **[John Alva](https://alvasystemsarchitecture.com)** — infrastructure and AI automation for organizations that can't afford downtime. | [Alva Systems](https://alvasystemsarchitecture.com)
## Changelog
### v0.2.0
- **New:** `tripartite_memory.guards.InjectionGuard` — zero-dependency prompt and shell injection scanner (stdlib only)
- **New:** `InjectionGuard.is_safe(text, threshold)` convenience method
- **Fix:** Narrowed backtick injection pattern — markdown inline code no longer triggers false positive
- **Fix:** Narrowed template literal pattern to only flag when shell operators are embedded (`${foo;rm}` triggers, `${VAR}` does not)
- **Lifecycle:** `nightly_pruning.py` default collections updated to generic names
- **Internal:** `format_as_stable_suffix` header string generalized
### v0.1.4
- Add stable suffix decoding support for prefix caching
### v0.1.3
- Add support for staleness filtering (`max_age_days`)
### v0.1.2
- Code review fixes and hardening
## Contributing
PRs are welcome. If you are building agentic systems that require strict intent multiplexing and deterministic safety, I'd love to collaborate.