Metadata-Version: 2.4
Name: contexara
Version: 0.2.2
Summary: CLI-first memory engine for LLM applications.
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
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"

# Contexara

A CLI-first memory engine for LLM applications. Drop it into any AI system and it remembers what matters — across sessions, without a vector database, without infra.

## Install

```bash
pip install contexara
```

Requires AWS credentials with Bedrock access (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`).

## How it works

Every conversation turn is analysed by an LLM (AWS Bedrock Haiku) and distilled into atomic facts. Facts are embedded with **Amazon Titan Text Embeddings V2** (1024-dim, serverless) and stored as BLOBs in a local SQLite file.

Retrieval uses **Reciprocal Rank Fusion** — semantic similarity and keyword overlap are ranked independently then fused. Temporal weighting boosts recent task/constraint memories and stabilises profile/preference ones.

Memories are never deleted. When the store exceeds a budget, old memories are compressed into sharp facts by the LLM and originals move to an archive table — permanently recoverable. Every compressed memory carries a `compression_level` and is penalised in retrieval. Raw memories win ties.

## CLI

```bash
contexara ask "what was I working on?"     # memory-aware Q&A
contexara store "prefers Python"           # store a memory
contexara ingest notes.txt                 # bulk ingest .txt / .md / .jsonl
contexara list                             # all memories
contexara list --since 2026-04-01          # filter by date
contexara search "tech stack"             # semantic search
contexara show <id>                        # full detail for one memory
contexara stats                            # counts, sources, age
contexara consolidate                      # LLM-compress all memories
contexara prune                            # archive expired (TTL) memories
contexara prune --dry-run                  # preview without changes
contexara delete <id>                      # delete one memory
contexara chat                             # interactive chat mode
```

## Chat mode

```text
contexara chat

  Contexara Chat  type 'exit' to quit
  Commands: /store /list /show <id> /delete <id> /search /stats /consolidate /clear

You: what am I building?
──────────────────────────────────────────────
You're building Contexara — a CLI-first memory engine...
──────────────────────────────────────────────
```

## Use in code

```python
from contexara import ask, store, retrieve, ingest_turn

store("User prefers concise answers")
ingest_turn(user_text, assistant_text)   # auto-extracts + deduplicates memories
answer = ask("what do I prefer?")
memories = retrieve("python preferences", top_k=5)
```

## Stack

| Layer      | Technology                                                          |
|------------|---------------------------------------------------------------------|
| Storage    | SQLite — embeddings as BLOBs, archive table for compressed memories |
| Embeddings | Amazon Titan Text Embeddings V2 (1024-dim, via Bedrock)             |
| LLM        | AWS Bedrock Haiku — extraction, compression, Q&A                    |
| Retrieval  | RRF hybrid search + temporal weighting + source-aware ranking       |
| CLI        | Python + rich                                                       |

## What's in v0.2.2

- **Bedrock embeddings** — replaced local BERT (2GB) with Titan V2, no model loading
- **File ingest** — bulk seed memory from `.txt`, `.md`, `.jsonl` files
- **TTL expiry** — `contexara prune` enforces expires_at, auto-sweeps on write
- **Date filters** — `--since` / `--before` on `list` and `search`
- **Rich terminal UI** — colored tables, spinner, progress bar, markdown responses
- **Fast-path ingest** — low-signal turns skip the LLM entirely
- **Temporal weighting** — recent tasks rank higher, profiles stay stable
- **Compression improvements** — 0.75 similarity threshold, time-bucketed grouping

---

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