Mneno: Instructions file for Codex

AGENTS.md

Project Overview

Mneno is a Python-first SDK for AI memory. It is an anti-context-rot memory runtime for copilots, support agents, internal AI tools, and long-running AI applications.

Mneno should maintain useful, compact, explainable, and verifiable context over time. It is not a generic memory store and should not become a thin wrapper around provider APIs.

Repository Structure

• mneno/: core Python package.
• mneno/scoring/: memory scoring interfaces and temporal scoring.
• mneno/compaction/: explainable compaction interfaces and diff templates.
• mneno/conflicts/: deterministic conflict detection, reports, and safe resolution policies.
• mneno/hierarchy/: memory layer definitions, retention policies, and lifecycle transition management.
• mneno/observability/: local trace models, in-memory recorder, and inspector utilities.
• mneno/evaluation/: deterministic metrics, benchmark adapters, operation reports, and stable export helpers.
• mneno/retrieval/: retrieval interfaces.
• mneno/storage/: storage interfaces and local in-memory storage.
• mneno/providers/: provider protocols, dummy local providers, and provider registry.
• mneno/policies/: runtime policy configuration.
• tests/: pytest suite.
• examples/: runnable usage examples.
• scripts/: development, formatting, and test commands.
• docs/: project documentation.

Development Setup

Use Python 3.11 or newer.

scripts/setup_dev.sh

The setup script uses uv when available and falls back to pip with a local virtual environment.

Build, Lint, and Test Commands

scripts/format.sh
scripts/check.sh
scripts/test.sh
python -m build

scripts/check.sh must pass before a pull request is ready.

Core APIs

The main public entrypoint is:

from mneno import MemoryClient

The initial client supports local in-memory add and search operations. Public APIs must be documented and covered by tests when they are added or changed.