Memnon

Reusable agent memory runtime for durable observations, cached profiles, and prompt-ready recall.

Memnon turns normalized agent sessions into long-lived memory. It extracts atomic observations, stores them by workspace, owner, and subject, builds cached representations, and retrieves relevant context for future runs.

Install

pip install memnon
pip install "memnon[postgres,pydantic-ai]"

For local development:

uv sync --extra dev
uv run pytest

Python API

from datetime import UTC, datetime

from memnon import PeerKind, PeerRef
from memnon.factory import create_memory_runtime
from memnon.types import InitializeRequest, MemoryMessage, MessageRole, SearchRequest, SessionEnvelope

runtime = create_memory_runtime(mode="test")

user = PeerRef(id="user-1", kind=PeerKind.USER)
agent = PeerRef(id="agent-1", kind=PeerKind.AGENT)

session = SessionEnvelope(
    workspace_id="workspace-1",
    session_id="thread-1",
    source_id="thread-1",
    peers=[user, agent],
    messages=[
        MemoryMessage(
            id="m1",
            peer_id="user-1",
            role=MessageRole.USER,
            content="I prefer short bullet summaries.",
            timestamp=datetime.now(UTC),
        ),
    ],
)

await runtime.initialize(
    InitializeRequest(workspace_id="workspace-1", targets=[user], sessions=[session])
)

result = await runtime.search(
    SearchRequest(workspace_id="workspace-1", owner=user, query="How should I summarize?")
)
print(result.context)

CLI

The CLI works with the Postgres runtime:

export MEMNON_DATABASE_URL="postgresql+asyncpg://localhost:5432/memnon"
memnon schema init
memnon ingest session session.json --target user:user-1
memnon search "How should I summarize?" --workspace workspace-1 --owner user:user-1
memnon representation get --workspace workspace-1 --owner user:user-1

For real LLM extraction through OpenRouter:

export OPENROUTER_API_KEY=...
MEMNON_MODEL=openrouter:openrouter/free memnon ingest session session.json --target user:user-1

Concepts

• owner: the peer that owns the memory space.
• subject: the peer the memory is about.
• Observation: an atomic durable fact extracted from a session.
• Representation: a cached prompt-facing profile built from observations.
• SessionEnvelope: normalized conversation data supplied by host applications.

Releasing

Tags trigger the release workflow. Configure PyPI trusted publishing in the GitHub release environment, then:

git tag v0.1.1
git push origin v0.1.1

See docs/ for the full API, CLI, and Postgres reference.

Evals

Memnon includes a Pydantic Evals smoke benchmark that runs live observation extraction, prompt-memory search, and automatic profile generation against OpenRouter:

OPENROUTER_API_KEY=... uv run --extra all python benchmarks/openrouter_memory_eval.py
OPENROUTER_API_KEY=... uv run --extra all pytest -m llm

The default model is openrouter/free; pass --model to the benchmark or set MEMNON_OPENROUTER_MODEL for the pytest smoke test.