Metadata-Version: 2.4
Name: cognitive-memory-layer
Version: 1.0.9
Summary: Python SDK for CognitiveMemoryLayer — neuro-inspired memory for AI
Project-URL: Homepage, https://github.com/avinash-mall/CognitiveMemoryLayer
Project-URL: Documentation, https://github.com/avinash-mall/CognitiveMemoryLayer/tree/main/packages/py-cml#readme
Project-URL: Repository, https://github.com/avinash-mall/CognitiveMemoryLayer
Project-URL: Issues, https://github.com/avinash-mall/CognitiveMemoryLayer/issues
Project-URL: Changelog, https://github.com/avinash-mall/CognitiveMemoryLayer/blob/main/packages/py-cml/CHANGELOG.md
Author: CognitiveMemoryLayer Team
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: ai,cognitive,llm,memory,rag,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Provides-Extra: embedded
Requires-Dist: aiosqlite>=0.20; extra == 'embedded'
Requires-Dist: asyncpg>=0.30; extra == 'embedded'
Requires-Dist: neo4j>=5.0; extra == 'embedded'
Requires-Dist: openai>=1.0; extra == 'embedded'
Requires-Dist: pgvector>=0.3; extra == 'embedded'
Requires-Dist: pydantic-settings>=2.0; extra == 'embedded'
Requires-Dist: redis>=5.0; extra == 'embedded'
Requires-Dist: sentence-transformers>=3.0; extra == 'embedded'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'embedded'
Requires-Dist: structlog>=24.0; extra == 'embedded'
Requires-Dist: tiktoken>=0.8; extra == 'embedded'
Description-Content-Type: text/markdown

# cognitive-memory-layer

**Python SDK for the Cognitive Memory Layer** — neuro-inspired memory for AI applications. Store, retrieve, and reason over memories with sync/async clients or an in-process embedded engine.

[![PyPI](https://img.shields.io/pypi/v/cognitive-memory-layer)](https://pypi.org/project/cognitive-memory-layer/)
[![Python](https://img.shields.io/pypi/pyversions/cognitive-memory-layer)](https://pypi.org/project/cognitive-memory-layer/)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

---

## Installation

```bash
pip install cognitive-memory-layer
```

**Embedded mode** (run the CML engine in-process, no server):

```bash
pip install cognitive-memory-layer[embedded]
```

Embedded mode requires the CML engine from the monorepo. From the repo root:

```bash
pip install -e .
pip install -e packages/py-cml[embedded]
```

---

## Quick start

**Sync client** (connect to a CML server):

```python
from cml import CognitiveMemoryLayer

with CognitiveMemoryLayer(api_key="sk-...", base_url="http://localhost:8000") as memory:
    memory.write("User prefers vegetarian food.")
    result = memory.read("What does the user eat?")
    print(result.context)  # Formatted for LLM injection
    turn = memory.turn(user_message="What should I eat tonight?", session_id="session-001")
    print(turn.memory_context)
```

**Async client:**

```python
import asyncio
from cml import AsyncCognitiveMemoryLayer

async def main():
    async with AsyncCognitiveMemoryLayer(api_key="sk-...", base_url="http://localhost:8000") as memory:
        await memory.write("User prefers dark mode.")
        result = await memory.read("user preferences")
        print(result.context)

asyncio.run(main())
```

**Embedded mode** (no server; SQLite + local embeddings):

```python
import asyncio
from cml import EmbeddedCognitiveMemoryLayer

async def main():
    async with EmbeddedCognitiveMemoryLayer() as memory:
        await memory.write("User prefers vegetarian food.")
        result = await memory.read("dietary preferences")
        print(result.context)

asyncio.run(main())
# Persistent: EmbeddedCognitiveMemoryLayer(db_path="./my_memories.db")
```

---

## Configuration

**Environment variables** (use `.env` or set directly): `CML_API_KEY`, `CML_BASE_URL`, `CML_TENANT_ID`, `CML_TIMEOUT`, `CML_MAX_RETRIES`, `CML_ADMIN_API_KEY`, `CML_VERIFY_SSL`. See [Configuration](docs/configuration.md).

**Constructor:**

```python
memory = CognitiveMemoryLayer(
    api_key="sk-...",
    base_url="http://localhost:8000",
    tenant_id="my-tenant",
)
```

Or use `CMLConfig` for validated, reusable config: `from cml import CMLConfig`.

---

## Features

| Mode | Description |
|------|-------------|
| **Client** | Sync and async HTTP clients for a running CML server; context managers |
| **Embedded** | In-process engine (lite mode: SQLite + local embeddings); no server |

**Memory API:** `write`, `read`, `turn`, `update`, `forget`, `stats`, `get_context`, `create_session`, `get_session_context`, `delete_all`

**Advanced:** `batch_write`, `batch_read`, `consolidate`, `run_forgetting`, `with_namespace`, `iter_memories`, `list_tenants`, `get_events`, `component_health`

**OpenAI integration:** `CMLOpenAIHelper(memory_client, openai_client)` — `helper.chat(user_message, session_id=...)` for memory-augmented chat. Set `OPENAI_MODEL` or `LLM__MODEL` in `.env`.

**Developer:** `read_safe` (returns empty on connection/timeout), `memory.session(name=...)` for scoped session injection, `configure_logging("DEBUG")`, typed models (`py.typed`)

**Temporal fidelity:** Optional `timestamp` in `write()`, `turn()`, `remember()` for historical data replay (benchmarks, migration, testing).

---

## Documentation

- [Getting Started](docs/getting-started.md)
- [API Reference](docs/api-reference.md)
- [Configuration](docs/configuration.md)
- [Examples](docs/examples.md)

[GitHub repository](https://github.com/avinash-mall/CognitiveMemoryLayer) — source, issues, server setup

[CHANGELOG](CHANGELOG.md)

---

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).
