Metadata-Version: 2.4
Name: contexara
Version: 2.3.1
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

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

# Load session context (T1 turns + T2 episode anchor)
ctx = mem.context(n=20)

# Memory stats
stats = mem.stats()

# Force crystallize current session
mem.checkpoint()
```

### Build Your Own Agent

```python
from contexara import ContextaraClient
from contexara.retrieve import retrieve, retrieve_episodes
from contexara.enhance import enhance
from contexara.llm import call_llm
from contexara.ingest import ingest_turn, flush_extraction

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

ctx = mem.context(n=20)
session_id = ctx["session_id"]
episode_anchor = ctx.get("episode_summary")
recent_turns = ctx.get("turns", [])

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in ("exit", "quit"):
        flush_extraction(session_id, namespace=NAMESPACE)
        break

    memories = retrieve(user_input, top_k=5, namespace=NAMESPACE)
    episode_hits = retrieve_episodes(user_input, top_k=3, namespace=NAMESPACE)

    prompt = enhance(
        user_input,
        memories,
        recent_turns=recent_turns or None,
        episode_anchor=episode_anchor,
        episode_hits=episode_hits or None,
    )

    reply = call_llm(prompt)
    print(f"Assistant: {reply}")

    recent_turns.append({"role": "user", "content": user_input})
    recent_turns.append({"role": "assistant", "content": reply})

    ingest_turn(user_input, reply, session_id=session_id, namespace=NAMESPACE)
    episode_anchor = None
```

---

## 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
- **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)
