contextengine-ai 0.1.0

A lightweight, vendor-agnostic context & memory engine for LLM applications

ContextEngine

ContextEngine is a lightweight, vendor-agnostic, pip-installable context & memory engine for LLM applications.

It adds state and memory to otherwise stateless LLM API calls by automatically storing, retrieving, and trimming past interactions.

This is infrastructure — not a chatbot framework.

---

✨ Why ContextEngine?

Most LLM APIs are stateless:

• Every API call forgets the past
• Developers manually manage history
• Context windows overflow unpredictably

ContextEngine solves this by providing:

• Automatic memory storage (input + output)
• Semantic-first retrieval (real memory)
• Hybrid context (memory + conversation flow)
• Token-safe context trimming
• Pluggable storage (In-memory, MongoDB, more later)
• Zero vendor lock-in

---

🚀 Features

• ✅ Auto-save interactions by default
• ✅ Semantic memory (embedding-based)
• ✅ Hybrid retrieval (semantic + recent)
• ✅ Session-based isolation
• ✅ Token-budget aware context trimming
• ✅ InMemoryStore (dev / testing)
• ✅ MongoMemoryStore (production persistence)
• ✅ Fully vendor-agnostic
• ✅ Deterministic & inspectable behavior

---

📦 Installation

Core (no database dependency)

pip install contextengine

With MongoDB support

pip install pymongo

(ContextEngine keeps database dependencies optional.)

---

🧠 Core Concepts

ContextUnit

The atomic unit of memory:

(role, content, session_id, metadata, timestamp)

Session

A user-defined identifier that isolates memory:

session_id="user_123"

MemoryStore

Pluggable backend for persistence:

• InMemoryStore
• MongoMemoryStore
• (FAISS / others later)

---

🔧 Quick Start (In-Memory)

from contextengine import (
    ContextEngine,
    ContextConfig,
    InMemoryStore,
    SentenceTransformerEncoder,
)

engine = ContextEngine(
    store=InMemoryStore(),
    encoder=SentenceTransformerEncoder(),
    config=ContextConfig(session_id="demo")
)

engine.store_interaction(
    input="My name is Albi",
    output="Nice to meet you Albi"
)

context = engine.get_context(query="What is my name?")
print(context)

---

🗄️ Using MongoDB (Persistent Memory)

from contextengine import ContextEngine, ContextConfig, SentenceTransformerEncoder
from contextengine.memory.mongo import MongoMemoryStore

engine = ContextEngine(
    store=MongoMemoryStore(
        uri="mongodb://localhost:27017",
        db_name="contextengine"
    ),
    encoder=SentenceTransformerEncoder(),
    config=ContextConfig(session_id="user_42")
)

engine.store_interaction(
    input="I live in Kerala",
    output="Kerala is in India"
)

context = engine.get_context(query="Where do I live?")
print(context)

---

✂️ Token-Safe Context Trimming

ContextEngine automatically enforces a token budget.

ContextConfig(
    session_id="chat",
    max_tokens=2048,
    token_estimator="chars"  # or "words"
)

• Oldest messages are removed first
• Order is preserved
• No vendor-specific tokenizers required

---

🧪 Testing

pytest

Tests run against:

• InMemoryStore
• MongoMemoryStore

Same behavior guaranteed.

---

🎯 Non-Goals

ContextEngine intentionally does NOT include:

• UI
• Agent frameworks
• Workflow orchestration
• Prompt templates
• LLM clients

It is a memory layer, not an app framework.

---

🧭 Roadmap

• FAISS / vector DB backend
• Custom token estimators
• Policy-based trimming
• Optional summaries
• Streaming support

---

📜 License

MIT License

---

👤 Author

Built independently as an open-source infrastructure project.

---