# samiksha0shukla/context-memory architecture

> Architecture diagram of the GitHub repository samiksha0shukla/context-memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samiksha0shukla/context-memory
- Repository: https://github.com/samiksha0shukla/context-memory

## Overview

#### 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.

Main entry points: [`src/contextmemory/memory/memory.py`](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/memory.py) (Memory facade), [`src/contextmemory/core/openai_client.py`](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/core/openai_client.py) (Provider client), [`src/contextmemory/memory/extractor.py`](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/extractor.py) (Semantic extractor), [`src/contextmemory/memory/add/add_updation_phase.py`](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/add/add_updation_phase.py) (Update phase)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host application"]
  node_host_app["Chat host"]
end

subgraph group_api["Library facade"]
  node_package_api["Package API<br/>Python exports<br/>[__init__.py]"]
  node_main["Repository script<br/>Python entrypoint<br/>[main.py]"]
  node_memory["Memory facade<br/>operational API<br/>[memory.py]"]
end

subgraph group_pipeline["Memory pipeline"]
  node_add_extraction["Extraction phase<br/>ingestion stage"]
  node_extractor["Semantic extractor<br/>LLM extraction<br/>[extractor.py]"]
  node_extraction_prompt["Extraction prompt<br/>prompt template"]
  node_update_phase["Update phase<br/>mutation decision"]
  node_tool_classifier["Tool classifier<br/>LLM classifier<br/>[tool_classifier.py]"]
  node_tool_prompt["Tool-call prompt<br/>prompt template"]
  node_bubble_creator["Bubble creator<br/>episodic memory<br/>[bubble_creator.py]"]
  node_connection_finder["Connection finder<br/>memory association"]
end

subgraph group_storage["Persistence and retrieval"]
  node_embeddings["Embedding generator<br/>vectorization<br/>[embeddings.py]"]
  node_vector_store[("FAISS vector index<br/>vector store<br/>[vector_store.py]")]
  node_similar_search["Similarity search<br/>ranked retrieval"]
  node_database[("Database sessions<br/>SQLAlchemy setup<br/>[database.py]")]
  node_records[("Domain records<br/>relational models<br/>[memory.py]")]
end

subgraph group_provider["Model provider"]
  node_settings["Global settings<br/>configuration<br/>[settings.py]"]
  node_openai_client{{"Provider client<br/>LLM boundary<br/>[openai_client.py]"}}
end

node_host_app -->|"uses"| node_package_api
node_package_api -->|"exports"| node_memory
node_main -->|"invokes"| node_memory
node_host_app -->|"search then add"| node_memory
node_memory -->|"add"| node_add_extraction
node_add_extraction -->|"extracts candidates"| node_extractor
node_extractor -->|"uses"| node_extraction_prompt
node_extractor -->|"LLM request"| node_openai_client
node_memory -->|"classifies mutation"| node_update_phase
node_update_phase -->|"uses"| node_tool_classifier
node_tool_classifier -->|"uses"| node_tool_prompt
node_tool_classifier -->|"LLM decision"| node_openai_client
node_update_phase -->|"creates episodic memory"| node_bubble_creator
node_bubble_creator -->|"finds links"| node_connection_finder
node_memory -->|"indexes memories"| node_embeddings
node_embeddings -->|"embedding request"| node_openai_client
node_embeddings -->|"vectors"| node_vector_store
node_memory -->|"search"| node_similar_search
node_similar_search -->|"nearest neighbors"| node_vector_store
node_memory -->|"CRUD"| node_database
node_database -->|"persists"| node_records
node_connection_finder -->|"queries associations"| node_records
node_settings -.->|"configures"| node_openai_client
node_settings -.->|"selects backend"| node_database

click node_package_api "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/__init__.py"
click node_main "https://github.com/samiksha0shukla/context-memory/blob/main/main.py"
click node_memory "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/memory.py"
click node_settings "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/core/settings.py"
click node_openai_client "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/core/openai_client.py"
click node_add_extraction "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/add/add_extraction_phase.py"
click node_extractor "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/extractor.py"
click node_extraction_prompt "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/utils/extraction_system_prompt.py"
click node_update_phase "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/add/add_updation_phase.py"
click node_tool_classifier "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/tool_classifier.py"
click node_tool_prompt "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/utils/tool_call_system_prompt.py"
click node_bubble_creator "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/bubble_creator.py"
click node_connection_finder "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/connection_finder.py"
click node_embeddings "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/embeddings.py"
click node_vector_store "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/vector_store.py"
click node_similar_search "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/similar_memory_search.py"
click node_database "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/db/database.py"
click node_records "https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/db/models/memory.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_app toneBlue
class node_package_api,node_main,node_memory toneAmber
class node_add_extraction,node_extractor,node_extraction_prompt,node_update_phase,node_tool_classifier,node_tool_prompt,node_bubble_creator,node_connection_finder toneMint
class node_embeddings,node_vector_store,node_similar_search,node_database,node_records toneRose
class node_settings,node_openai_client toneIndigo
```

## Components

### Host application

Owns chat lifecycle and prompt composition.

- **Chat host**: application · Searches before generation and adds exchanges afterward.

### Library facade

- [Package API](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/__init__.py): Python exports · `src/contextmemory/__init__.py`
- [Repository script](https://github.com/samiksha0shukla/context-memory/blob/main/main.py): Python entrypoint · `main.py`
- [Memory facade](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/memory.py): operational API · Provides add, search, update, and delete. · `src/contextmemory/memory/memory.py`

### Memory pipeline

- [Extraction phase](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/add/add_extraction_phase.py): ingestion stage · Structures fact and episodic candidate extraction. · `src/contextmemory/memory/add/add_extraction_phase.py`
- [Semantic extractor](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/extractor.py): LLM extraction · `src/contextmemory/memory/extractor.py`
- [Extraction prompt](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/utils/extraction_system_prompt.py): prompt template · `src/contextmemory/utils/extraction_system_prompt.py`
- [Update phase](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/add/add_updation_phase.py): mutation decision · Decides add, update, replace, or ignore before persistence. · `src/contextmemory/memory/add/add_updation_phase.py`
- [Tool classifier](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/tool_classifier.py): LLM classifier · `src/contextmemory/memory/tool_classifier.py`
- [Tool-call prompt](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/utils/tool_call_system_prompt.py): prompt template · `src/contextmemory/utils/tool_call_system_prompt.py`
- [Bubble creator](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/bubble_creator.py): episodic memory · Creates time-bound episodic memories. · `src/contextmemory/memory/bubble_creator.py`
- [Connection finder](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/connection_finder.py): memory association · Links episodic events to related semantic memories. · `src/contextmemory/memory/connection_finder.py`

### Persistence and retrieval

- [Embedding generator](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/embeddings.py): vectorization · `src/contextmemory/memory/embeddings.py`
- [FAISS vector index](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/vector_store.py): vector store · Accelerates retrieval over persisted memories. · `src/contextmemory/memory/vector_store.py`
- [Similarity search](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/memory/similar_memory_search.py): ranked retrieval · `src/contextmemory/memory/similar_memory_search.py`
- [Database sessions](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/db/database.py): SQLAlchemy setup · Creates sessions for SQLite or PostgreSQL persistence. · `src/contextmemory/db/database.py`
- [Domain records](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/db/models/memory.py): relational models · Conversation, message, memory, and summary records scoped by conversation ID. · `src/contextmemory/db/models/memory.py`

### Model provider

- [Global settings](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/core/settings.py): configuration · Selects providers, credentials, debug mode, and database backend. · `src/contextmemory/core/settings.py`
- [Provider client](https://github.com/samiksha0shukla/context-memory/blob/main/src/contextmemory/core/openai_client.py): LLM boundary · Supports OpenAI and OpenRouter-compatible calls. · `src/contextmemory/core/openai_client.py`

## Connections

- Chat host → Package API: uses
- Package API → Memory facade: exports
- Repository script → Memory facade: invokes
- Chat host → Memory facade: search then add
- Memory facade → Extraction phase: add
- Extraction phase → Semantic extractor: extracts candidates
- Semantic extractor → Extraction prompt: uses
- Semantic extractor → Provider client: LLM request
- Memory facade → Update phase: classifies mutation
- Update phase → Tool classifier: uses
- Tool classifier → Tool-call prompt: uses
- Tool classifier → Provider client: LLM decision
- Update phase → Bubble creator: creates episodic memory
- Bubble creator → Connection finder: finds links
- Memory facade → Embedding generator: indexes memories
- Embedding generator → Provider client: embedding request
- Embedding generator → FAISS vector index: vectors
- Memory facade → Similarity search: search
- Similarity search → FAISS vector index: nearest neighbors
- Memory facade → Database sessions: CRUD
- Database sessions → Domain records: persists
- Connection finder → Domain records: queries associations
- Global settings → Provider client: configures
- Global settings → Database sessions: selects backend