Metadata-Version: 2.4
Name: memnon
Version: 0.1.0
Summary: Reusable agent memory runtime for durable observations, representations, and prompt recall.
Project-URL: Homepage, https://github.com/advantch/memnon
Project-URL: Repository, https://github.com/advantch/memnon
Project-URL: Issues, https://github.com/advantch/memnon/issues
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,memory,pgvector,pydantic-ai
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.8
Requires-Dist: rich>=13.9.4
Requires-Dist: typer>=0.16.1
Provides-Extra: all
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: pgvector>=0.3; extra == 'all'
Requires-Dist: pydantic-ai>=1.84.1; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.15.6; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Requires-Dist: pgvector>=0.3; extra == 'postgres'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'postgres'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai>=1.84.1; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# 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

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

For local development:

```bash
uv sync --extra dev
uv run pytest
```

## Python API

```python
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:

```bash
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
```

## 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:

```bash
git tag v0.1.0
git push origin v0.1.0
```

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

