samiksha0shukla/context-memory

Purpose and Public Entry Points

ContextMemory is a Python library that gives AI conversation systems durable, per-conversation memory. It extracts semantic facts and time-bound episodic “bubbles,” persists them, and retrieves relevant context for a later prompt. The package-facing API is exposed from src/contextmemory/__init__.py; the operational facade is src/contextmemory/memory/memory.py. A standalone repository entry script also exists at main.py.

Configuration and Provider Boundary

Global configuration selects LLM/embedding settings, credentials, debug behavior, and SQLite versus PostgreSQL persistence through src/contextmemory/core/settings.py. src/contextmemory/core/openai_client.py isolates model calls and supports direct OpenAI or OpenRouter-compatible models. Extraction, update classification, and embeddings therefore cross a remote-provider boundary rather than being implemented locally.

Relational Persistence Model

SQLAlchemy-style database setup and session creation are centralized in src/contextmemory/db/database.py. Persistent domain records are split across:

• src/contextmemory/db/models/conversation.py

• src/contextmemory/db/models/message.py

• src/contextmemory/db/models/memory.py

• src/contextmemory/db/models/conversation_summary.py

This is the durable source of truth, backed by default SQLite or configurable PostgreSQL. Conversation IDs scope writes and searches.

Add Pipeline: Extraction to Mutation

Memory.add() in src/contextmemory/memory/memory.py orchestrates ingestion. The extraction stage in src/contextmemory/memory/extractor.py sends the latest interaction to the configured LLM using src/contextmemory/utils/extraction_system_prompt.py, producing semantic facts and episodic candidates. src/contextmemory/memory/add/add_extraction_phase.py structures this extraction flow.

The update stage—src/contextmemory/memory/add/add_updation_phase.py—uses src/contextmemory/memory/tool_classifier.py and src/contextmemory/utils/tool_call_system_prompt.py to decide whether a candidate should be added, updated, replaced due to contradiction, or ignored. This separates probabilistic LLM decisions from database mutation.

Embeddings and Vector Retrieval

src/contextmemory/memory/embeddings.py generates vector representations through the configured embedding provider. src/contextmemory/memory/vector_store.py maintains the FAISS-backed vector index, while src/contextmemory/memory/similarity.py and src/contextmemory/memory/similar_memory_search.py perform ranked similarity lookup. Memory.search() combines a text query, conversation scope, and result limit to return matching stored memories; vector indexing is an acceleration layer over persisted memory records.

Episodic Connection Layer

Episodic memories are created by src/contextmemory/memory/bubble_creator.py. src/contextmemory/memory/connection_finder.py identifies related semantic memories and records/returns those associations. This makes current tasks or events navigable through durable user facts while retaining their distinct time-bound type.

Primary Control Flow and Ownership

A host application owns chat generation and calls the library around it: search before prompting, then add the new user/assistant exchange afterward. ContextMemory owns extraction, classification, embedding, vector search, persistence, and CRUD (add, search, update, delete) behind src/contextmemory/memory/memory.py. The host owns conversation lifecycle, prompt composition, database-session lifetime, and use of retrieved memories in its agent response.