Metadata-Version: 2.4
Name: contexara
Version: 2.4.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"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Requires-Dist: voyageai>=0.2.0; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.5.0; extra == "gemini"
Provides-Extra: openrouter
Requires-Dist: openai>=1.0.0; extra == "openrouter"
Provides-Extra: all-providers
Requires-Dist: openai>=1.0.0; extra == "all-providers"
Requires-Dist: anthropic>=0.20.0; extra == "all-providers"
Requires-Dist: voyageai>=0.2.0; extra == "all-providers"
Requires-Dist: google-generativeai>=0.5.0; extra == "all-providers"

# Contexara

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

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

[![PyPI version](https://img.shields.io/pypi/v/contexara)](https://pypi.org/project/contexara/)
[![Python](https://img.shields.io/pypi/pyversions/contexara)](https://pypi.org/project/contexara/)
[![License: MIT](https://img.shields.io/pypi/l/contexara)](LICENSE)

---

## Install

```bash
pip install contexara
contexara setup
contexara ask "what was I working on?"
```

For specific providers:

```bash
pip install contexara[openai]
pip install contexara[anthropic]
pip install contexara[gemini]
pip install contexara[all-providers]
```

---

## How It Works

| Tier | What | Scope |
|------|------|-------|
| **T1 — Raw Turns** | Every user/assistant message, stored verbatim | Current session |
| **T2 — Episodes** | LLM-crystallized summaries of past sessions | Cross-session |
| **T3 — Semantic Memory** | Extracted facts, preferences, constraints, corrections | Permanent |

On every query, all three tiers inject context automatically — your agent is never blind.

---

## Supported Providers

| Provider | `CONTEXARA_PROVIDER` value |
|----------|---------------------------|
| AWS Bedrock | `bedrock` (default) |
| OpenAI | `openai` |
| Anthropic | `anthropic` |
| Google Gemini | `gemini` |
| OpenRouter | `openrouter` |

Configure via `contexara setup` or manually in `~/.contexara/.env`:

```env
CONTEXARA_PROVIDER=openai
CONTEXARA_MODEL=gpt-4o
OPENAI_API_KEY=sk-...
```

---

## Python SDK

```python
from contexara import ContextaraClient
from contexara.llm import call_llm

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

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in ("exit", "quit"):
        mem.flush()   # extract memories from remaining turns on exit
        break

    prompt = mem.build_prompt(user_input)   # retrieve + enhance (T1+T2+T3)
    reply = call_llm(prompt)
    print(f"Assistant: {reply}")

    mem.ingest(user_input, reply)           # store turn + batch extract every 10 turns
```

### Additional SDK Methods

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

# Explicit memory operations
mem.store("User prefers bullet-point responses", kind="preference")
mem.retrieve("what does the user prefer?")   # returns [{content, kind}, ...]
mem.search("budget constraints")             # returns full records with metadata
mem.stats()                                  # memory counts by kind and source
mem.checkpoint()                             # force crystallize current session
mem.history(memory_id)                       # version history for a memory
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `contexara setup` | Configure AI provider credentials |
| `contexara ask "<query>"` | Single query with full memory context |
| `contexara chat` | Interactive chat mode |
| `contexara store "<text>"` | Save a memory directly |
| `contexara list` | List stored memories |
| `contexara search "<query>"` | Semantic search over memories |
| `contexara stats` | Memory counts by kind and source |
| `contexara consolidate` | LLM-merge overlapping memories |
| `contexara clear` | Delete all memories in namespace |
| `contexara namespace list\|create\|switch\|delete` | Manage namespaces |
| `contexara serve` | Start REST API server |
| `contexara dashboard` | Start web dashboard |
| `contexara mcp` | Start MCP server |

---

## Namespaces

Complete data isolation between agents or projects:

```bash
contexara namespace create work
contexara namespace switch work
contexara ask "what are my pending tasks?" --namespace work
```

---

## Key Features

- **Local first** — all data in `~/.contexara/`, no cloud required
- **LLM agnostic** — Bedrock, OpenAI, Anthropic, Gemini, OpenRouter
- **Batch extraction** — memories extracted every 10 turns for cost efficiency, flushed on exit
- **Intent classification** — detects historical vs. recent vs. semantic queries, adjusts retrieval strategy
- **Hybrid retrieval** — FTS5 + cosine vector search with RRF fusion
- **Multiplicative scoring** — memory ranked by similarity × importance × recency, per-kind decay
- **Memory observability** — tracks which memories were cited, usage ratio, and confidence signals per turn
- **Session continuity** — sessions crystallize after 60 min inactivity, injected on next session start
- **Never-delete versioning** — full history of every memory update
- **Cold archive** — turns older than 30 days auto-swept to FTS5-searchable archive
- **MCP server** — plug into Claude Desktop or any MCP-compatible framework
- **Web dashboard** — memory browser, session explorer, latency charts, LLM-as-judge evals

---

## Data Storage

```
~/.contexara/
├── memory.db          # T3 semantic memories
├── active_state.db    # T1 raw turns + T2 episodes + sessions
└── cold_archive.db    # archived turns older than 30 days
```

---

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