Metadata-Version: 2.4
Name: contexara
Version: 2.1.0
Summary: AI that forgets is just autocomplete. Contexara gives your agent a memory it can build on.
Author: Contexara Contributors
Project-URL: Homepage, https://github.com/Prajwal-Narayan/Contexara
Project-URL: Repository, https://github.com/Prajwal-Narayan/Contexara
Keywords: llm,memory,agentic-ai,retrieval,context
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.34.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: rich>=13.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"

# Contexara

> AI that forgets is just autocomplete. Contexara gives your agent a memory it can build on.

Persistent, three-tier memory engine for AI agents. Drop it in and your agent remembers facts, corrections, and past sessions — automatically, across every conversation.

## Install

```bash
pip install contexara
contexara setup        # configure AWS Bedrock credentials
contexara ask "what was I working on?"
```

Run setup on first install:

```bash
contexara setup
```

This guides you through AWS Bedrock credentials and saves them to `~/.contexara/.env`.

## How it works

| Tier | What it stores | When |
| --- | --- | --- |
| **L0** — Raw turns | Every user/assistant exchange verbatim | Every turn |
| **L1** — Episodes | LLM-crystallized session summaries | After session ends |
| **L2** — Semantic memory | Typed facts: preferences, corrections, constraints, tech choices | Every turn |

On session start, all three tiers inject context automatically — your agent is never blind.

## Python SDK

```python
from contexara import ContextaraClient

mem = ContextaraClient(namespace="my-agent")

ctx = mem.context()                        # inject history + last episode
facts = mem.retrieve("user preferences")  # hybrid search before answering
mem.ingest(user_text, assistant_text)     # extract + store after every turn
mem.store("User prefers bullet points", kind="style")  # explicit store
mem.checkpoint()                          # crystallize session now
```

## MCP Server

Works with Claude Desktop and any MCP-compatible framework:

```json
{ "mcpServers": { "contexara": { "command": "python", "args": ["-m", "contexara.mcp_server"] } } }
```

## What's in v2.1.0

- **9 memory kinds** — profile, correction, preference, constraint, tech\_preference, style, pattern, task, note
- **Zero fact-loss crystallization** — 3-pass LLM pipeline with fact audit and repair
- **Hybrid search** — FTS5 + cosine vector RRF on hot DB, FTS5 on cold archive
- **Never-delete versioning** — full history of every memory update
- **Namespace isolation** — separate memory space per agent or application
- **Model routing** — fast model for chat, judge model for extraction and evals
- **`~/.contexara/` storage** — persists across projects

---

## Memory model

| Tier | Stores | When |
|------|--------|------|
| Raw turns | Every message in the session | Live |
| Episodes | LLM-crystallized session summaries | On session close |
| Semantic facts | Extracted atomic memories | Permanent |
| Cold archive | Turns older than 30 days | FTS5, auto-swept |

Sessions idle for 60 minutes crystallize automatically in the background.

---

## Interfaces

**CLI** — `ask`, `store`, `search`, `list`, `chat`, `ingest`, `namespace`, `mcp`, `eval`

**MCP server** — 13 tools over stdio or SSE. Plug into Claude Desktop or any agent SDK.

**Python SDK**
```python
from contexara import ContexaraClient
client = ContexaraClient(namespace="my_agent")
client.memory.store("user prefers Python", kind="preference")
memories = client.memory.search("current goals")
client.chat.ingest(user_msg, assistant_msg)
```

**Dashboard**
```bash
contexara dashboard --port 8000
```
Latency charts, trace explorer, namespace management, LLM-as-judge eval scores — all in one UI.

---

**Stack:** SQLite · AWS Bedrock · Amazon Titan Embeddings · RRF hybrid retrieval · FastAPI · React

Built by [Prajwal Narayan](https://github.com/Prajwal-Narayan)
