Aegis Memory

Contents

• What is Aegis? — the 60-second overview + architecture
• Why it matters — agents are being compromised through memory
• Quickstart (2 minutes) — server, SDK, first multi-agent example
• Guard every write — the write boundary, in code
• Threat model — what Aegis defends, and what it doesn't
• Security capabilities — the six built-in protections
• The Context Hub — prompts + memory + skills + subagents in one call
• Memory Depth — hybrid retrieval, contradictions, consolidation
• Context that improves itself (ACE) — agents that learn
• How Aegis compares — vs mem0, Zep, Letta
• What's shipped vs roadmap — no marketing ahead of code
• Security benchmark — does the detector actually work?
• Performance — latency and throughput numbers
• Deployment and configuration
• Documentation · Contributing · License

What is Aegis?

Aegis Memory is a secure memory and context layer for AI agents. It does what a memory library does — store, search, rank, and share what your agents know — but it treats every piece of content as untrusted until it's screened. A single gate sits in front of memory: clean writes persist, poisoned writes are rejected and never stored.

You can adopt it three ways, from lightest to fullest:

• aegis_memory.guard — a local, offline write-gate you wrap around any store (LangGraph, a vector DB, your own). No server required.
• aegis inspect — a static analyzer that scans your agent code for unsafe memory-write flows and points each finding at the guard fix.
• The Aegis server — a full FastAPI service with PostgreSQL + pgvector: ranked retrieval, multi-agent access control, the Context Hub, the ACE learning loop, and an audit trail.

flowchart TD
    A[Python SDK: AegisClient] -->|HTTP Bearer API key| B[FastAPI Server]
    A2[SmartMemory / SmartAgent] --> A
    A3[Framework Integrations: CrewAI / LangChain] --> A
    A4[MCP Server] --> A
    A5[CLI] --> A

    B --> C[Auth + Rate Limit Dependencies]
    C --> D[Memory / ACE / Typed / Interaction Routers]
    D --> E[Content Security Scanner]
    D --> F[Embedding Service]
    D --> G[Repository Layer]
    G --> H[(PostgreSQL + pgvector)]
    F --> H
    D --> I[Event Repository]
    I --> H

    N[Local Mode: SQLite + numpy] -. no server .-> A
    O[aegis_memory.guard] -. local write gate .-> P[External Memory Store]
    Q[aegis inspect / replay] -. static/offline .-> O

Why it matters

Agents are getting compromised. Not theoretically — right now.

• EchoLeak (CVE-2025-32711, CVSS 9.3) — a single email triggered zero-click data exfiltration from Microsoft 365 Copilot[^echoleak]
• CrewAI + GPT-4o — researchers achieved a 65% exfiltration success rate against multi-agent systems (COLM 2025)[^crewai]
• Drift chatbot cascade — one compromised chatbot integration cascaded into 700+ organizations via Salesforce, Google Workspace, Slack, S3, and Azure[^drift]
• OWASP Top 10 for Agentic Applications (December 2025) lists memory and context manipulation as a top risk category[^owasp-top10]

Agent A's output is Agent B's instruction. Memory is the vector.

Every other memory layer trusts content by default. That is the vulnerability. Aegis screens it.

Quickstart (2 minutes)

Start the server

git clone https://github.com/quantifylabs/aegis-memory.git
cd aegis-memory

export OPENAI_API_KEY=sk-...
docker compose up -d

curl http://localhost:8000/health
# {"status": "healthy"}

Install the SDK

pip install aegis-memory

Multi-agent context in 10 lines

from aegis_memory import AegisClient

client = AegisClient(api_key="dev-key", base_url="http://localhost:8000")

# Planner agent stores a task breakdown
client.add(
    content="Task: Build login. Steps: 1) Form, 2) Validation, 3) API",
    agent_id="planner",
    scope="agent-shared",
    shared_with_agents=["executor"],
)

# Executor queries the planner's memories
memories = client.query_cross_agent(
    query="current task",
    requesting_agent_id="executor",
    target_agent_ids=["planner"],
)
print(memories[0].content)

Full Quickstart Guide →

Guard every write

Gate the write, and the topology stops mattering. Across every multi-agent shape (cooperative blackboard, hierarchical handoff, swarm, competitive), the invariant is the same: something becomes durable memory and a later step reads it back and acts on it. aegis_memory.guard is the one scope-aware gate every topology funnels through. It runs the same benchmark-validated ContentSecurityScanner the server does — offline, deterministic, no server required:

from aegis_memory import guard

# Wrap any store (LangGraph / vector DB / custom) — every write is screened before it persists.
store = guard.protect(my_store, scope="agent-shared")
store.put(ns, key, {"text": untrusted_web_content})   # a poisoned write never reaches memory

# …or screen a single value inline before you persist it.
verdict = guard.write(content, trust_level="untrusted", scope="agent-shared", on_reject="return")
if verdict.allowed:
    my_store.put(ns, key, {"text": verdict.content})

The gate rejects prompt-injection and secrets, flags PII, and refuses to let untrusted content land in global scope (where every agent would read it). aegis inspect finds the unsafe write sites; guard is the fix it points you at.

Threat model

A short, honest statement of what Aegis defends and how — drawn from the Security Guide.

What it defends against

Trust levels label content provenance: untrusted (external/user/tool content) → internal (default server trust) → privileged (admin-capable) → system (highest). Scopes control who can read a memory: agent-private (owner only) → agent-shared (owner + explicitly shared agents) → global (any agent in the project/namespace). The core rule: screened-clean content is allowed into private/shared scopes, but untrusted content is blocked from global, because promotion there means every agent reads it.

Two different things are called "trust" here and the distinction is load-bearing. A memory's trust_level labels the content's provenance — where the data came from — and governs what scope it may reach. An API key's trust level describes the principal and governs what that caller may do. Both are checked on a write; the shared rule lives in aegis_memory/scope_policy.py so guard and the server cannot drift.

[!IMPORTANT] Agent identity comes from the API key, not the request body. Bind a key to an agent (bound_agent_id) and that identity is authoritative: a request claiming a different agent_id is rejected with 403, and the scope ACL is evaluated against the bound agent. This is what makes agent-private a boundary rather than a convention.

An unbound key represents the whole application and may act as any agent in its project — that is the documented posture for a project-scoped key, not a bypass. Agent-level isolation is available to callers who opt into bound keys; an unbound key has no agent identity to check against. Project isolation is always enforced.

What it does not do (limitations)

• Agent-level isolation requires bound API keys. An unbound project key can act as any agent in its project by design — bind keys per agent when agents must be mutually isolated.
• TrustPolicy's principal rules (an internal key may not write global) are enforced only when ENABLE_TRUST_LEVELS=true, since enabling them requires a privileged key for global writes. The content-provenance rule — untrusted content may never reach global — is always enforced.
• Regex-only stages (1–3) miss adaptive/semantic injection; Stage 4 (LLM classifier) improves coverage but adds latency and an API call, and can drift with the model/provider.
• Integrity hashing detects tampering — it does not encrypt content. If AEGIS_INTEGRITY_KEY is compromised, hashes can be forged.
• The in-memory rate limiter is single-instance; horizontal deployments need the Redis limiter.
• Some local-mode operations do not run the full server-side security scan.

Security capabilities

Aegis implements OWASP AI Agent Security recommendations natively. Six capabilities, none optional:

1. 4-stage content security pipeline — input validation, sensitive-data scanning, prompt-injection detection, and an optional LLM-based injection classifier. On every memory write.
2. HMAC-SHA256 integrity signing — tamper detection on store, verification on demand. You know if a memory was modified.
3. OWASP 4-tier trust hierarchy — untrusted, internal, privileged, system. Agents get compromised; Aegis limits the blast radius.
4. Cryptographic agent binding — every route resolves its project from the authenticated key, and for agent-bound keys its acting agent too. A bound key can't be talked into a request body that says "I'm the admin agent." Unbound project keys act for the whole application — see Threat model.
5. ACE loop — generation, reflection, curation. Agents that learn from their own mistakes and promote what works.
6. Multi-agent coordination — scoped access control, cross-agent query, structured handoffs. Memory sharing with boundaries.

flowchart TD
    A[Incoming memory content] --> B[Stage 1: validate length + metadata]
    B --> C[Stage 2: detect PII/secrets]
    C --> D[Stage 3: regex injection detection]
    D --> E{Need Stage 4?}
    E -->|untrusted/unknown or shared/global or injection flags| F[Optional LLM classifier]
    E -->|no| G[Policy decision]
    F --> G
    G -->|reject| H[Block write + SECURITY_REJECTED]
    G -->|redact| I[Store redacted content + flags]
    G -->|flag| J[Store content + flags + review]
    G -->|allow| K[Store content]

The Context Hub

(v2.3.0+) Aegis is the only OSS context hub. Four artifacts, one secure surface, one API call to load them all:

Every artifact: HMAC integrity-signed. Content-scanned. Trust-gated. Audit-logged.

from aegis_memory import AegisClient
client = AegisClient(api_key="...")

bundle = client.load_context(
    agent_id="executor",
    query="paginate the orders API",
    token_budget=8000,
)
# → ranked memories + active prompt + matched skills + available subagents
# → integrity-verified across all four
# → token-budgeted to fit your model

Other context hubs (LangSmith, MindStudio) are closed-source. Other memory layers (mem0, Zep, Letta) stop at memory. Aegis does both, with security as the foundation.

Memory Depth

(v2.4.0) Beyond storing memories, Aegis owns their lifecycle. mem0, Zep, and Letta ship variants of these primitives; what's distinct in Aegis is the audit-preserving, human-reviewable shape of each one — typed edges with explicit resolution states, consolidation that soft-deprecates rather than deletes.

Every query runs through dense (pgvector cosine) and sparse (PostgreSQL tsvector) channels, fused with Reciprocal Rank Fusion. Catches the exact-match cases (entity names, error codes, tool names, file paths) that pure embedding similarity blurs.

results = client.hybrid_query(query="ZX7-PAGE-94 cursor pagination", agent_id="executor")

When two memories make incompatible claims, Aegis surfaces the conflict as a contradicts edge — a typed link with confidence and rationale. Resolve via API.

client.scan_contradictions(namespace="default")
unresolved = client.list_contradictions()
client.resolve_edge(edge_id=..., resolution="kept_source")
metrics = client.contradiction_metrics()
# → {"unresolved_contradictions": 3, "total_contradictions_detected": 17}

Real merge, not prefix matching. Embedding-similar memories above threshold get merged via heuristic or LLM, with full audit trail (the losing memory stays queryable with is_deprecated=True and metadata.consolidated_into).

plan = client.consolidate_memories(dry_run=True)   # review first
client.consolidate_memories(dry_run=False)         # then apply

Context that improves itself (ACE)

Aegis Memory ships a complete ACE loop — the Generation → Reflection → Curation cycle from Stanford/SambaNova's research, engineered for production. Your agent made the same mistake 5 times? The ACE loop remembers the fix. Stale memories polluting retrieval? Curation auto-cleans your playbook.

flowchart TD
    A[Start run] --> B[Query playbook / memories]
    B --> C[Execute task]
    C --> D[Complete run]
    D --> E{success?}
    E -->|yes| F[Auto-vote helpful on used memories]
    E -->|no| G[Auto-vote harmful on used memories]
    G --> H[Auto-create reflection if error info exists]
    F --> I[Update effectiveness]
    H --> I
    I --> J[Curate: promote, flag, suggest consolidation]
    J --> K[Future playbook retrieval]

from aegis_memory import AegisClient

client = AegisClient(api_key="your-key")

# 1. GENERATION: Query agent-specific playbook
playbook = client.get_playbook_for_agent(
    "executor",
    query="API pagination task",
    task_type="api-integration",
)
memory_ids = [e.id for e in playbook.entries]

# 2. EXECUTION: Track which memories the agent uses
run = client.start_run(
    "task-42", "executor",
    task_type="api-integration",
    memory_ids_used=memory_ids,
)

# ... agent does its work ...

# 3. REFLECTION: Complete with outcome (auto-feedback!)
client.complete_run("task-42", success=True, evaluation={"score": 0.95})
# -> Auto-votes 'helpful' on every memory used
# -> On failure: auto-votes 'harmful' AND creates a reflection memory

# 4. CURATION: Periodically clean up
curation = client.curate(namespace="production")
# -> Promotes high-effectiveness entries
# -> Flags low-effectiveness for deprecation
# -> Identifies duplicate entries to consolidate

ACE Patterns Guide →

How Aegis compares

Different tools solve different problems. Memory-depth primitives (hybrid retrieval, contradiction handling, consolidation) are now table stakes — mem0, Zep, Letta, and Aegis all ship variants in 2026.[^memory-depth-sources] The differences are in how, not whether — and in the security layer underneath. This comparison stays focused on capabilities documented in public repos and docs.[^comparison]

Pick the tool that fits the job:

Pick Aegis Memory when most of these are true:

• You need content security — injection detection, integrity verification, sensitive-data protection.
• You need multiple agents to share memory safely with explicit ACL/scopes.
• You need handoffs where one agent passes a reliable state bundle to another.
• You want ACE patterns (vote/reflection/playbook) to continuously improve memory quality.
• You want hybrid retrieval that catches exact-token cases (entity names, error codes, file paths) without giving up semantic similarity.
• You need contradiction tracking that's reviewable, not just auto-deleted — typed edges with explicit kept_source / kept_target / both_valid / both_invalid resolutions, plus a /metrics endpoint.
• You need consolidation with an audit trail — losing memories stay queryable rather than being deleted.
• You prefer a self-host posture with operational control over storage and deployment.
• You need temporal decay so stale memories don't pollute retrieval over time.

What's shipped vs roadmap

Everything described above is shipped and released on PyPI as of aegis-memory v2.6.0 (2026-06-25). No feature in this README is aspirational.

Directions we're exploring (not commitments — track them in Discussions and the Changelog): broader injection coverage via the adaptive attack harness, and continued benchmark hardening.

Security benchmark

Does the 4-stage content security pipeline actually catch prompt injection? We measured it as a detector against five baselines (DeBERTa, LLM Guard, Llama Prompt Guard 2, and two LLM judges) on labelled injection + benign corpora — full confusion matrices, a per-stage ablation, bootstrapped 95% CIs, and pinned dataset revisions. The false-positive rate is reported next to recall everywhere — a blocker that flags everything is useless.

Aegis's threat model is indirect injection: text written into memory that manipulates an agent when it is later retrieved. That is what the first table measures. Direct injection — a user pasting "ignore previous instructions" into a prompt — is a different problem, reported below.

Indirect injection / memory poisoning — InjecAgent, N=250

The deterministic core matches DeBERTa within overlapping CIs at ~2,800× lower latency, with no model download and no API call. Stage 4 is shown with Claude; the GPT-4o-mini variant scores 0.744 [0.69–0.80]. FPR is undefined on this corpus — all 250 cases are malicious — so over-defense is measured separately below.

One caveat we report rather than bury. On indirect injection, Stage 2 (PII/secrets) flags 155/250 payloads and accounts for most of the deterministic core's recall here. That is not injection detection working — it is Stage 2 firing on the credentials and health records embedded in data-exfiltration payloads. The write is still blocked, and catching a data-stealing payload via a different stage is the point of a multi-category pipeline, but it is not a better injection regex. The genuine injection signal is the Stage 3 → Stage 4 delta in the full report.

Over-defense — NotInject, N=339 benign sentences seeded with injection trigger words. Every sample is benign, so lower is better. This is where learned detectors tend to fall over.

Direct injection — deepset/prompt-injections, N=662. Not Aegis's threat model, kept visible because it is where the deterministic core is weakest: Stages 1–3 score 0.144 recall (matching naive_regex, since injection text rarely contains PII for Stage 2 to catch), rising to 0.741 with the Claude classifier. Both at 0.000 FPR.

→ Full results, ablation, baselines, latency, and limitations: docs/security/benchmark.md · reproduce with python benchmarks/injection/run_benchmark.py.

Performance

Benchmarked on 8 vCPU / 7.6 GB RAM (Intel 13th Gen), 1000 memories, Docker Compose (PostgreSQL 16

• pgvector), concurrency=10. Queries include OpenAI embedding latency. Reproduce with cd benchmarks && bash run_benchmark.sh.

Query tail latency (p95/p99) is dominated by the external OpenAI embedding call, not Aegis or PostgreSQL. Write and vote operations that skip embedding are consistently under 100ms at p50.

Deployment and configuration

# Docker Compose
docker compose up -d

# Kubernetes
kubectl apply -f k8s/

Full Configuration →

Documentation

docs.aegismemory.com — full documentation

• Quickstart — get running in 5 minutes
• Security Guide — content security, integrity, trust hierarchy
• ACE Patterns — self-improving agent patterns
• Smart Memory — zero-config memory extraction
• Integrations — CrewAI, LangChain guides
• CLI Reference — command-line tools

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Run tests
pytest tests/ -v

# Run linting
ruff check server/

License

Apache 2.0 — use it however you want. See LICENSE.

Links: Documentation · GitHub Discussions · Issue Tracker · Changelog

Built by engineers who read the OWASP reports and acted on them.

[^echoleak]: EchoLeak: Zero-click exfiltration from M365 Copilot. arxiv.org/html/2509.10540v1 [^crewai]: Multi-agent exfiltration study (COLM 2025). openreview.net/pdf?id=DAozI4etUp [^drift]: CVE-2025-32711 zero-click AI vulnerability analysis. socprime.com/blog/cve-2025-32711-zero-click-ai-vulnerability/ [^owasp-top10]: OWASP Top 10 for Agentic Applications (2026). genai.owasp.org [^comparison]: Security comparison based on public documentation and open-source repositories as of February 2026. Sources: mem0 docs | Zep docs | Letta repo | Aegis docs [^memory-depth-sources]: Memory-depth feature claims verified May 2026 against vendor blogs and docs. Sources: mem0 State of AI Agent Memory 2026 (hybrid: semantic + BM25 + entity), mem0 architecture (consolidation, Mem0g contradiction resolver), Graphiti / Zep paper and Neo4j writeup (LLM-based edge contradiction with temporal invalidation), Letta archival search docs (RRF hybrid). Aegis design choices documented in server/contradiction_detector.py and server/consolidation.py.