{"id":49096876,"url":"https://github.com/lavadman/aegis-memory","last_synced_at":"2026-04-20T21:01:23.875Z","repository":{"id":348165660,"uuid":"1196534554","full_name":"LavaDMan/aegis-memory","owner":"LavaDMan","description":"Tripartite memory SDK for AI agents: semantic recall, structural graph awareness, and relational state — before agents act.","archived":false,"fork":false,"pushed_at":"2026-04-20T17:27:46.000Z","size":104,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T19:28:30.508Z","etag":null,"topics":["agentic-ai","ai-agents","autonomous-agents","llm","memory","neo4j","python","qdrant","rag","vector-database"],"latest_commit_sha":null,"homepage":"https://alvasystemsarchitecture.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LavaDMan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T19:44:38.000Z","updated_at":"2026-04-20T17:27:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LavaDMan/aegis-memory","commit_stats":null,"previous_names":["lavadman/aegis-memory"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/LavaDMan/aegis-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LavaDMan%2Faegis-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LavaDMan%2Faegis-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LavaDMan%2Faegis-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LavaDMan%2Faegis-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LavaDMan","download_url":"https://codeload.github.com/LavaDMan/aegis-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LavaDMan%2Faegis-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32065584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","autonomous-agents","llm","memory","neo4j","python","qdrant","rag","vector-database"],"created_at":"2026-04-20T21:01:01.599Z","updated_at":"2026-04-20T21:01:23.856Z","avatar_url":"https://github.com/LavaDMan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AEGIS Tripartite Memory SDK 🧠\nAvailable on PyPI as **tripartite-memory**\n\n[![PyPI Version](https://img.shields.io/pypi/v/tripartite-memory.svg)](https://pypi.org/project/tripartite-memory/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/)\n\nMost 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.\n\nThis is **AI Amnesia**.\n\n`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:\n\u003e \"Has this failed before?\"  \n\u003e \"What will this impact?\"  \n\u003e \"Is this safe to execute?\"\n\nInstead of guessing, it **knows.**\n\n## Memory \u0026 Context Optimization ⚡\n`tripartite-memory` significantly reduces the cost and improves the performance of running large models:\n- **60-80% Token Reduction:** Instead of dumping massive chat histories into the prompt, `recall()` injects only the 3-5 most relevant precedents.\n- **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.\n- **Improved Reasoning:** Providing specific \"Hard Constraints\" from the Ledger prevents the LLM from making up rules, leading to deterministic and reliable outputs.\n\n## What This Fixes\n**Without memory:**\n- Agents loop on failed solutions.\n- Context windows explode with irrelevant history.\n- Risky actions happen without awareness of dependencies.\n\n**With `tripartite-memory`:**\n- Agents avoid known failure paths.\n- Context stays small and relevant.\n- Actions are informed by real system state and \"trace the real blast radius.\"\n\n## The Tripartite Architecture\nTo make an LLM safe for production, it needs an operating-system-level memory stack:\n1. **The Ledger (Postgres):** Immutable state, strict constraints, and audit logs.\n2. **The Semantic Engine (Qdrant):** High-dimensional vector search for historical precedents and documentation.\n3. **The Capability Graph (Neo4j):** Dependency mapping to understand how modifying Component A impacts System B.\n\n## Installation\n\n```bash\npip install tripartite-memory\n```\n\n## Quickstart\nInitialize the `MemoryCore` with your database credentials (or use a `.env` file).\n\n```python\nimport asyncio\nfrom tripartite_memory.core import MemoryCore\n\nasync def main():\n    # Automatically loads from .env\n    memory = MemoryCore()\n\n    # 1. Unified Ingestion (Write to all 3 databases simultaneously)\n    await memory.ingest(\n        content=\"Modified the Nginx reverse proxy to route /api/v2 traffic to staging.\",\n        actor=\"agent:InfrastructureOps\",\n        tags=[\"nginx\", \"networking\", \"staging\"]\n    )\n\n    # 2. Pre-Action Context Check (The Blast Radius)\n    # Give your agent complete situational awareness before it touches production.\n    context = await memory.recall(\n        intent=\"Restart the Nginx service to apply new SSL certificates.\",\n        graph_depth=2\n    )\n\n    print(context.status) # \"KNOWN\", \"ADJACENT\", or \"UNKNOWN\"\n    print(context.blast_radius) # Neo4j dependent nodes\n    print(context.historical_precedents) # Qdrant vector matches\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## The Agent Protocol 🛡️\n`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.\n\n## Universal Integration\n- **Local Models (Ollama/LM Studio):** Inject the `recall()` JSON directly into the context window before the user's prompt.\n- **CLI Clients (Claude Code/Gemini CLI):** Wrap the SDK in a tool or use the provided **Bridge Script**.\n\n## Bi-directional Memory Bridge 🔄\nA ready-to-use bridge is included in [examples/bridge.py](./examples/bridge.py) that works on Linux, Mac, and Windows.\n\n```bash\n# Get Context\npython examples/bridge.py recall \"How do I optimize VRAM on Pascal?\"\n\n# Store Knowledge\npython examples/bridge.py ingest \"Successfully tuned batch size to 4 for Qwen-32B.\" --tags optimization\n```\n\n## Remote Connection Guide (LAN) 🌐\nIf testing from a remote machine, point the SDK to your server's IP in your `.env`:\n```ini\nPOSTGRES_URL=postgresql://user:password@10.0.0.100:5432/aegis_local\nQDRANT_URL=http://10.0.0.100:6333\nNEO4J_URI=bolt://10.0.0.100:7687\nNEO4J_PASSWORD=your-secure-password\nOLLAMA_URL=http://10.0.0.100:11434\n```\n\n## Managed Cloud Support ☁️\n`tripartite-memory` is compatible with major managed database providers. Just update your `.env` with the cloud connection strings:\n\n- **Vector (Qdrant):** Works with [Qdrant Cloud](https://qdrant.tech/cloud/). Set `QDRANT_API_KEY` in your environment.\n- **Graph (Neo4j):** Works with [Neo4j AuraDB](https://neo4j.com/cloud/aura/). Use your provided `bolt://` URI and password.\n- **Ledger (Postgres):** Works with [Neon](https://neon.tech/) or [Supabase](https://supabase.com/).\n\n```ini\n# Cloud Example\nQDRANT_URL=https://your-cluster.qdrant.tech\nQDRANT_API_KEY=your-api-key\nNEO4J_URI=bolt+s://your-instance.databases.neo4j.io\n```\n\n## Injection Guard 🛡️\n\n`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.\n\n```python\nfrom tripartite_memory.guards import InjectionGuard\n\n# Quick boolean check\nif not InjectionGuard.is_safe(user_input):\n    raise ValueError(\"Input rejected by injection guard\")\n\n# Full report\nresult = InjectionGuard.scan_text_for_injection(user_input)\n# {\n#   \"score\": 50,           # 0 = clean, ≥50 = high-risk\n#   \"findings\": [{\"severity\": \"HIGH\", \"description\": \"...\", \"pattern\": \"...\"}],\n#   \"summary\": \"Injection scan score: 50. 1 finding(s).\"\n# }\n```\n\n**What it detects (HIGH risk, score +50 each):**\n- `shell=True` in subprocess, `os.system()`, `eval()`, `exec()`\n- Container privilege escalation (`--privileged`, `cap_add SYS_ADMIN`)\n- Prompt override attempts (`ignore previous instructions`, `act as`, etc.)\n- HTML/JS injection (`\u003cscript\u003e`, `javascript:`)\n- Malicious shell commands (`rm -rf`, `sudo`, `wget`, `curl`, etc.)\n- Template injection with shell operators (`${foo;rm -rf}`)\n- Backtick shell execution (`` `rm -rf /` `` — not triggered by markdown inline code)\n\n**Medium risk (score +10 each):** security TODOs, `DEBUG=True`, logical operator chaining.\n\nScores cap at 100. Pure stdlib — no install overhead.\n\n## SBOM \u0026 Transparency\n\nThis repository includes a **Software Bill of Materials (SBOM)** in CycloneDX format.\n- **View SBOM:** [sbom.json](./sbom.json)\n- **Generate Fresh SBOM:** `python scripts/generate_sbom.py`\n\n## Why I Built This\nI 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).\n\nWhile 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).\n\nBuilt by **[John Alva](https://alvasystemsarchitecture.com)** — infrastructure and AI automation for organizations that can't afford downtime. | [Alva Systems](https://alvasystemsarchitecture.com)\n\n## Changelog\n\n### v0.2.0\n- **New:** `tripartite_memory.guards.InjectionGuard` — zero-dependency prompt and shell injection scanner (stdlib only)\n- **New:** `InjectionGuard.is_safe(text, threshold)` convenience method\n- **Fix:** Narrowed backtick injection pattern — markdown inline code no longer triggers false positive\n- **Fix:** Narrowed template literal pattern to only flag when shell operators are embedded (`${foo;rm}` triggers, `${VAR}` does not)\n- **Lifecycle:** `nightly_pruning.py` default collections updated to generic names\n- **Internal:** `format_as_stable_suffix` header string generalized\n\n### v0.1.4\n- Add stable suffix decoding support for prefix caching\n\n### v0.1.3\n- Add support for staleness filtering (`max_age_days`)\n\n### v0.1.2\n- Code review fixes and hardening\n\n## Contributing\nPRs are welcome. If you are building agentic systems that require strict intent multiplexing and deterministic safety, I'd love to collaborate.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flavadman%2Faegis-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flavadman%2Faegis-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flavadman%2Faegis-memory/lists"}