mnemon-ai 1.0.3

The intelligence layer between your agents and oblivion

Mnemon

The intelligence layer between your agents and oblivion.

---

The Problem

Every major agent framework — CrewAI, Letta, Dify, LangChain — treats agents as stateless by default. Every run starts from zero. Agents re-plan things they already planned. They repeat mistakes they already made. They forget what they learned last session. Parallel agents step on each other's state.

This isn't a small inconvenience. It's why production agent deployments are fragile, slow, and expensive at scale.

Mnemon fixes this. Drop it in and your agents stop being amnesiac.

Mnemon was Alexander the Great's personal historian — the one whose only job was to ensure nothing was ever forgotten, so every campaign built on the total accumulated knowledge of every campaign before it. Your agents have a Mnemon now.

---

Three Components

mnemon.memory — Cognitive Memory System

Five-layer stratified memory with protein bond activation retrieval and conditional intent drone curation.

• Working — ephemeral scratchpad, flushes at task end (no context bleed)
• Episodic — chronological experiences, importance-scored
• Semantic — stable facts, versioned key-value vault
• Relationship — per-user interaction patterns
• Emotional — emotional context, time-decayed

Retrieval: two-part — protein bond pattern assembly (zero LLM, ~15ms) followed by conditional intent drone (only above memory pool threshold).

mnemon.cache — Execution Memory Engine (EME)

Generalised execution template cache for any expensive recurring computation.

• System 1 — exact fingerprint match → zero LLM, sub-millisecond
• System 2 — partial segment match → gap fill with windowed context
• Fragment library — 49 pre-warmed proven segments, grows with use
• Works for agent plans, RAG pipelines, data pipelines, any structured workflow

mnemon.bus — Two-Tier Experience Bus

Tier 1 — system learning loop, always on, no agents needed. Records outcomes, detects patterns, feeds EME and memory.

Tier 2 — agent intelligence layer. PAD health monitoring (Pleasure/Arousal/Dominance), knowledge propagation (collective immunity), atomic belief registry (shared truth for swarms).

---

Quick Start

pip install mnemon-ai

Includes out of the box:

• sentence-transformers — real 384-dim semantic embeddings (~85%+ retrieval precision)
• cryptography — Fernet AES-128 encryption for sensitive memory
• anthropic — LLM routing, auto-activated when ANTHROPIC_API_KEY is set

import asyncio
from mnemon import Mnemon

async def main():
    async with Mnemon(tenant_id="my_company", agent_id="agent_01") as m:

        # Remember something
        await m.remember("Acme Corp prefers formal PDF reports")
        await m.learn_fact("acme_contact", "Sarah K")

        # Recall relevant memories
        context = await m.recall("weekly security audit for Acme Corp")

        # Run with full execution caching
        result = await m.run(
            goal="weekly security audit for Acme Corp",
            inputs={"client": "Acme Corp", "week": "March 17-21"},
            generation_fn=my_expensive_planning_function,
        )

        print(f"Cache level:  {result['cache_level']}")
        print(f"Tokens saved: {result['tokens_saved']}")
        print(f"Latency:      {result['latency_ms']:.0f}ms")

asyncio.run(main())

---

Connect Your LLM

Set one environment variable. Mnemon detects it automatically — no code changes needed.

# Anthropic — Claude (claude-haiku for routing, claude-sonnet for generation)
pip install mnemon-ai[anthropic]
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI — GPT (gpt-4o-mini for routing, gpt-4o for generation)
pip install mnemon-ai[openai]
export OPENAI_API_KEY=sk-...

# Google — Gemini (gemini-flash for routing, gemini-pro for generation)
pip install mnemon-ai[google]
export GOOGLE_API_KEY=AIza...

# Groq — Llama3 (free tier available — no credit card needed)
pip install mnemon-ai[groq]
export GROQ_API_KEY=gsk_...

Mnemon checks keys in that order and picks the first one it finds. No configuration beyond setting the key.

# No llm_client= argument needed — auto-detected from environment
async with Mnemon(tenant_id="my_company", agent_id="agent_01") as m:
    ...

Or pass explicitly if you prefer:

from mnemon.llm.client import AnthropicClient, OpenAIClient, GoogleClient, GroqClient

m = Mnemon(tenant_id="x", llm_client=GroqClient())  # free tier

---

Modular — Use Only What You Need

# Memory only
m = Mnemon(tenant_id="x", eme_enabled=False, bus_enabled=False)

# Execution cache only
m = Mnemon(tenant_id="x", memory_enabled=False, bus_enabled=False)

# Specific memory layers only
from mnemon.core.models import MemoryLayer
m = Mnemon(
    tenant_id="x",
    enabled_layers=[MemoryLayer.EPISODIC, MemoryLayer.SEMANTIC],
    eme_enabled=False,
    bus_enabled=False,
)

---

Framework Adapters

from mnemon.adapters.crewai import CrewAIAdapter
from mnemon.adapters.letta import LettaAdapter

m = Mnemon(tenant_id="my_company", adapter=CrewAIAdapter())

Write your own by subclassing TemplateAdapter:

from mnemon.core.eme import TemplateAdapter

class MyAdapter(TemplateAdapter):
    def decompose(self, template): ...
    def reconstruct(self, segments): ...
    def extract_signature(self, template, goal): ...

---

Production Features

from mnemon import Mnemon
from mnemon.security.manager import TenantSecurityConfig

m = Mnemon(
    tenant_id="my_company",
    # Security — blocks PII, encrypts privileged content
    security_config=TenantSecurityConfig(
        tenant_id="my_company",
        blocked_categories=["pii", "medical_records"],
        encrypt_privileged=True,
    ),
    # Observability — health checks, self-healing, metrics
    enable_watchdog=True,
    enable_telemetry=True,
)

---

Fail-Safe Design

Mnemon never crashes the system it serves.

• Memory retrieval fails → agent runs without context
• EME fails → generation_fn called directly
• Bus fails → agent continues unmonitored
• Database unavailable → in-memory fallback mode
• All failures logged, never raised

---

Architecture

Any AI system
      ↓ adapter translates
┌──────────────────────────────────────────┐
│  EME      Execution Memory Engine        │  S1 → S2 → generation
│  Memory   Five-layer cognitive memory    │  protein bonds → intent drone
│  Bus      Two-tier experience bus        │  Tier 1 always / Tier 2 for agents
└──────────────────────────────────────────┘
           ↓
    SQLite (local) / Redis (scale)

---

Package Structure

mnemon/
├── core/
│   ├── models.py        ← all shared dataclasses and enums
│   ├── persistence.py   ← SQLite + inverted index + migrations
│   ├── memory.py        ← five-layer memory + protein bonds + drone
│   ├── eme.py           ← execution memory engine S1/S2
│   └── bus.py           ← two-tier experience bus + PAD
├── adapters/
│   ├── crewai.py        ← CrewAI adapter
│   └── letta.py         ← Letta/MemGPT adapter
├── llm/
│   └── client.py        ← Anthropic, OpenAI, Mock clients + auto_client()
├── security/
│   └── manager.py       ← content filtering, encryption, isolation
├── observability/
│   ├── watchdog.py      ← health checks, self-healing, alerts
│   └── telemetry.py     ← structured metrics
├── eval/
│   └── harness.py       ← eval suite with scoring
├── fragments/
│   └── library.py       ← 49 pre-warmed execution fragments
└── cli/
    └── main.py          ← mnemon init/eval/health/stats

---

Issues Filed — Problems Mnemon Solves

Documented on the frameworks themselves:

• CrewAI #4415 — context pollution and DB write contention
• Dify #32306 — redundant reasoning tax in agent nodes
• Kimi CLI #1058 — context saturation in 100-agent swarms
• E2B #1207 — environmental amnesia in sandboxes
• Letta RFC — heartbeat contention and sleep-time compute integration

---

License

MIT — free to use, free to build on.