Metadata-Version: 2.4
Name: chronos-mem
Version: 0.1.0
Summary: PostgreSQL-backed structured memory and causal debugging engine for autonomous AI agents.
Project-URL: Homepage, https://github.com/JCHETAN26/Chronos-mem
Project-URL: Repository, https://github.com/JCHETAN26/Chronos-mem
Project-URL: Issues, https://github.com/JCHETAN26/Chronos-mem/issues
Author: chronos-mem
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai-agents,llm,memory,observability,pgvector,postgres
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: psycopg[binary,pool]>=3.2
Requires-Dist: pydantic>=2.6
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'
Description-Content-Type: text/markdown

# chronos-mem (Python SDK)

Async, typed client for the chronos-mem agent memory engine.

```python
import asyncio
from chronos_mem import ChronosClient

async def main():
    async with ChronosClient(dsn="postgresql://chronos:chronos@localhost:5432/chronos_mem") as db:
        plan = await db.create_plan(agent_id="agent-1", goal="Book a vacation to Tokyo")

        action = await db.log_action(
            plan_id=plan.id,
            tool_name="flights.search",
            payload={"from": "SFO", "to": "HND"},
        )

        await db.log_outcome(
            action_id=action.id,
            status="success",
            result={"cheapest_usd": 812},
        )

asyncio.run(main())
```

## Install (dev)

```bash
pip install -e ".[dev]"
```

The DSN can also be supplied via the `CHRONOS_DSN` environment variable instead
of the `dsn=` argument.

## Design

- **`client.py`** — `ChronosClient` owns one async `psycopg_pool` connection pool;
  open once per process and share it across concurrent agent calls.
- **`tracking.py`** — `create_plan` / `log_action` / `log_outcome`, the three core
  write verbs, each a single `INSERT ... RETURNING *`.
- **`models.py`** — Pydantic v2 models (`Plan`, `Action`, `Outcome`, `Memory`)
  mirroring the SQL schema in `db/migrations/001_init_chronos_schema.sql`.
