Metadata-Version: 2.4
Name: zeos-memory
Version: 0.1.0
Summary: Memory infrastructure for AI agents — persistent context, session governance, and three-tier memory
Project-URL: Homepage, https://github.com/zeroechelon/zeos
Project-URL: Documentation, https://github.com/zeroechelon/zeos/tree/main/zeos-memory
Project-URL: Repository, https://github.com/zeroechelon/zeos
Project-URL: Issues, https://github.com/zeroechelon/zeos/issues
Author-email: Zero Echelon <dev@zeroechelon.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,context,knowledge-graph,llm,mcp,memory,session-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: full
Requires-Dist: graphiti-core>=0.5; extra == 'full'
Requires-Dist: mcp>=1.0; extra == 'full'
Provides-Extra: graphiti
Requires-Dist: graphiti-core>=0.5; extra == 'graphiti'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# zeos-memory

Your AI agents remember.

## Install

```bash
pip install zeos-memory
```

## Quick Start

```python
from zeos_memory import ZeosMemory

zm = ZeosMemory(project_id="my-project", agent="claude")
zm.start_session()
zm.snap(delta="Built the auth module")
zm.snap(delta="Added JWT validation")
journal, memory = zm.end(
    summary="Authentication complete",
    delta="All tests passing",
    next_actions="Add refresh token rotation",
)
print(zm.render_memory())
```

## Features

- **Three-tier memory** — long-term (SOUL), mid-term (journals), short-term (working state)
- **Decay curation** — entries auto-archive by relevance score (0-6), pinned entries persist
- **Session lifecycle** — deterministic create/snap/end with continuity digests
- **Decision tracking** — first-class entities with rationale and alternatives
- **Agent-agnostic** — same protocol governs Claude, Gemini, Codex, Kimi
- **Zero dependencies** — core SDK needs only `pydantic`

## Optional Extras

```bash
pip install zeos-memory[mcp]       # MCP server for AI agents
pip install zeos-memory[graphiti]   # Temporal knowledge graph backend
pip install zeos-memory[full]       # Everything
```

## MCP Server

Add to your agent's MCP config:

```json
{
  "mcpServers": {
    "zeos-memory": {
      "command": "python",
      "args": ["-m", "zeos_memory"]
    }
  }
}
```

Tools: `zeos_boot`, `zeos_snap`, `zeos_recall`, `zeos_curate`, `zeos_end`.

## Architecture

| Tier | Content | Persistence |
|------|---------|-------------|
| **Long-Term** | SOUL identity, MEMORY.md | Permanent, rolling synopsis |
| **Mid-Term** | Session journals, blueprints | Session-scoped, summarized |
| **Short-Term** | Working state | Ephemeral, checkpointed |

Memory entries carry decay scores. Each session decrements non-pinned scores. Over-budget entries auto-archive. The system curates itself.

## Protocol

zeos is a governance and persistence protocol for AI agents. It runs IN context, not ON hardware. See the full [Protocol Specification](https://github.com/zeroechelon/zeos/blob/main/ZEOS_PROTOCOL_SPEC_v1.md).

## License

Apache-2.0
