Metadata-Version: 2.4
Name: contexara
Version: 1.0.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
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"

# Contexara

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

```bash
pip install contexara
contexara setup   # configure AWS Bedrock credentials
```

---

## How it works

Three tiers of memory, always in sync:

| Tier | What it stores | Lifecycle |
| --- | --- | --- |
| **1 — Raw turns** | Every message in the active session | Lives until session closes |
| **2 — Episodes** | LLM-crystallized session summaries | Created on session close (background) |
| **3 — Semantic facts** | Extracted atomic memories | Permanent, compressed when over budget |

Every `ask` pulls from all three tiers — recent turns for continuity, episode summary for session handoff, semantic memories for persistent facts.

Sessions close after 60 minutes of inactivity. A background worker crystallizes them into structured summaries (title, actions, outcomes, open items) without blocking the user.

Cold archive: raw turns older than 30 days sweep automatically to a SQLite FTS5 store — full-text searchable across years of history.

---

## CLI

```bash
contexara ask "what was I working on?"
contexara store "prefers Python"
contexara ingest notes.md               # bulk ingest .txt / .md / .jsonl
contexara list
contexara list --since 2026-04-01
contexara search "tech stack"
contexara show <id>
contexara delete <id>
contexara stats
contexara consolidate                   # LLM-compress overlapping memories
contexara prune                         # archive expired (TTL) memories
contexara chat                          # interactive chat mode
```

### Namespaces

Isolate memory per agent, project, or user:

```bash
contexara namespace create coding_agent
contexara namespace list
contexara namespace remove coding_agent

contexara ask "what am I building?" --namespace coding_agent
contexara chat --namespace coding_agent
```

### MCP server

Expose Contexara as an MCP tool server — lets AI agents manage their own memory autonomously:

```bash
contexara mcp                          # stdio (Claude Desktop, agent SDKs)
contexara mcp --sse --port 8000        # SSE for HTTP agents
```

13 tools available: `chat_ingest`, `chat_context`, `memory_store`, `memory_search`, `memory_list`, `memory_forget`, `memory_deprecate`, `memory_stats`, `episodes_search`, `episodes_latest`, `session_checkpoint`, `archive_search`, `namespace_list`.

---

## Python SDK

```python
from contexara import ContexaraClient

client = ContexaraClient(namespace="coding_agent")

# Before responding — load context
memories = client.memory.search("user's current goal")
recent = client.chat.get_recent_turns(n=10)
episodes = client.episodes.search("what did I work on last week?")

# After responding — save the turn
client.chat.ingest(user_message, assistant_response)

# When you learn something worth remembering
client.memory.store("user prefers typed Python", kind="preference", importance=3)

# When a major task finishes
client.episodes.crystallize()
```

All write operations have async equivalents (`astore`, `aingest`, `acrystallize`, etc.).

---

## Stack

| Layer | Technology |
|-------|------------|
| Storage | SQLite — raw turns, episodes, memories, cold archive (FTS5) |
| Embeddings | Amazon Titan Text Embeddings V2 via Bedrock |
| LLM | AWS Bedrock — extraction, crystallization, Q&A |
| Retrieval | RRF hybrid search + temporal weighting |
| Transports | CLI · Python SDK · MCP (stdio + SSE) |

---

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