# AI Context Manager
A modular context management system for AI-powered applications with intelligent summarization and feedback learning.
## Features
- **Modular Architecture**: Pluggable components, stores, and summarizers
- **Token-Aware Budgeting**: Intelligent context management with automatic summarization
- **Feedback Learning**: Time-weighted scoring system for component prioritization
- **Multiple Storage Backends**: JSON and SQLite support
- **Privacy-Focused**: Local LLM support via Ollama
- **Flexible Summarization**: OpenAI, Ollama, and naive summarizers
## Quick Start
### 1. Install Dependencies
**Basic Installation:**
```bash
pip install -e .
```
**With ChromaDB Support (Development):**
```bash
pip install -e .[vector]
```
**With PostgreSQL Support (Production):**
```bash
pip install -e .[production]
```
**Full Installation (All Features):**
```bash
pip install -e .[all]
```
### 2. Set Up Environment Variables
Copy `env.example` to `.env` and configure:
```bash
cp env.example .env
```
Edit `.env` with your settings:
```env
# Required for OpenAI summarizer
OPENAI_API_KEY=your_openai_api_key_here
# Optional Ollama configuration
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=mistral
```
### 3. Configure the System
Edit `config.toml` based on your setup:
**For production agents (PostgreSQL + pgvector):**
```toml
[summarizer]
type = "auto_fallback" # Tries Ollama, falls back to naive
model = "mistral"
[feedback_store]
type = "sqlite"
db_path = "feedback.db"
[memory_store]
type = "postgres_vector" # Enterprise-grade vector database
host = "localhost"
port = 5432
database = "ai_context"
user = "postgres"
password = "your_password"
table_name = "agent_memory"
embedding_dimension = 384
index_type = "hnsw"
```
**For development agents (ChromaDB):**
```toml
[summarizer]
type = "auto_fallback" # Tries Ollama, falls back to naive
model = "mistral"
[feedback_store]
type = "json"
filepath = "feedback.json"
[memory_store]
type = "vector" # ChromaDB semantic similarity search
collection_name = "agent_memory"
persist_directory = "./chroma_db"
embedding_model = "all-MiniLM-L6-v2"
```
**For automatic fallback (simpler setup):**
```toml
[summarizer]
type = "auto_fallback" # Tries Ollama, falls back to naive
model = "mistral"
[feedback_store]
type = "json"
filepath = "feedback.json"
[memory_store]
type = "json"
filepath = "memory.json"
```
**For local development (no external dependencies):**
```toml
[summarizer]
type = "naive" # Simple truncation, works anywhere
[feedback_store]
type = "json"
filepath = "feedback.json"
[memory_store]
type = "json"
filepath = "memory.json"
```
**When on your local network with Ollama:**
```toml
[summarizer]
type = "ollama"
model = "mistral"
# host will be read from OLLAMA_HOST environment variable
[feedback_store]
type = "json"
filepath = "feedback.json"
[memory_store]
type = "json"
filepath = "memory.json"
```
**For OpenAI integration:**
```toml
[summarizer]
type = "openai"
model = "gpt-3.5-turbo"
# api_key will be read from OPENAI_API_KEY environment variable
[feedback_store]
type = "json"
filepath = "feedback.json"
[memory_store]
type = "json"
filepath = "memory.json"
```
### 4. Basic Usage
```python
from ai_context_manager import ContextManager, TaskSummaryComponent
from ai_context_manager.config import Config
from ai_context_manager.utils import load_stores_from_config, load_summarizer
# Load configuration
config = Config("config.toml")
feedback_store, memory_store = load_stores_from_config(config.data)
# Initialize context manager
ctx = ContextManager(
feedback_store=feedback_store,
memory_store=memory_store,
summarizer=load_summarizer(config)
)
# Add a component
task = TaskSummaryComponent(
id="task-001",
task_name="Example Task",
summary="This is an example task summary",
tags=["example", "demo"]
)
ctx.register_component(task)
# Get context
context = ctx.get_context(
include_tags=["example"],
token_budget=500,
summarize_if_needed=True
)
print(context)
```
## Configuration
### Summarizers
- **auto_fallback**: **Recommended** - Tries Ollama first, falls back to naive (best of both worlds)
- **naive**: Simple truncation (no external dependencies) - **works anywhere**
- **ollama**: Local LLM via Ollama API (requires local Ollama instance)
- **openai**: OpenAI GPT models (requires API key and internet)
### Storage
- **JSON**: File-based storage for simple deployments
- **SQLite**: Database storage for production use
- **Vector**: ChromaDB-based semantic similarity search (development)
- **PostgreSQL + pgvector**: Enterprise-grade vector database (production)
### Network Scenarios
**Automatic Fallback (Recommended):**
- Use `type = "auto_fallback"` in config.toml
- Automatically tries Ollama when available, falls back to naive when not
- Perfect for switching between networks
- Set `OLLAMA_HOST=http://192.168.0.156:11434` in .env for your network
**Offline/Local Development:**
- Use `type = "naive"` in config.toml
- No external dependencies required
- Perfect for development and testing
**On Your Local Network:**
- Set `type = "ollama"` in config.toml
- Set `OLLAMA_HOST=http://192.168.0.156:11434` in .env
- Requires Ollama running on your local network
**Internet Access:**
- Set `type = "openai"` in config.toml
- Set `OPENAI_API_KEY=your_key` in .env
- Requires OpenAI API access
## Security
- API keys are loaded from environment variables
- No sensitive data is stored in configuration files
- Local-first approach with Ollama support
## Running Tests
```bash
python test_runner.py
```
## CLI Usage
The AI Context Manager includes a command-line interface for easy management:
```bash
# Initialize a new project
ai-context init
# Show system status
ai-context status
# Search for content
ai-context search "AI trends"
# Get context for a query
ai-context context "research findings"
# Add content
ai-context add task --id t1 --name "Research" --content "Found insights"
ai-context add learning --id l1 --content "Vector DBs are faster" --source "testing"
# Manage configuration
ai-context config show
ai-context config optimize --use-case agent
```
## Performance Benchmarking
Run performance benchmarks to test your system:
```bash
python benchmark_performance.py
```
## Quick Examples
Try the quick start examples:
```bash
python examples/quick_start.py
```
## Architecture
```
ai_context_manager/
├── components/ # Context component types
├── store/ # Storage backends
├── summarizers/ # Summarization engines
├── config.py # Configuration management
├── context_manager.py # Main context manager
├── feedback.py # Feedback learning system
└── utils.py # Utility functions
```
## Vector Database Benefits
**Development (ChromaDB):**
- ✅ **Easy setup** - No database server required
- ✅ **Fast prototyping** - Perfect for local development
- ✅ **Semantic search** - Natural language queries
- ✅ **Lightweight** - Minimal dependencies
**Production (PostgreSQL + pgvector):**
- ✅ **Enterprise-grade** - ACID transactions, backup/recovery
- ✅ **Horizontal scaling** - Read replicas, connection pooling
- ✅ **Advanced indexing** - HNSW/IVFFlat for sub-millisecond queries
- ✅ **Full-text search** - Combined with vector similarity
- ✅ **Monitoring** - Built-in observability and metrics
**Performance:**
- 🚀 **10x faster** than traditional keyword search
- 🚀 **Sub-millisecond** vector similarity queries
- 🚀 **Concurrent access** with connection pooling
- 🚀 **Memory efficient** with advanced indexing
**Installation:**
```bash
# Development
pip install ai-context-manager[vector]
# Production
pip install ai-context-manager[production]
```
## Recent Improvements
- ✅ **PostgreSQL + pgvector**: Added enterprise-grade vector database support
- ✅ **Production Setup**: Complete production deployment guide
- ✅ **Vector Database**: Added ChromaDB-based semantic similarity search
- ✅ **Semantic Context Manager**: Enhanced context retrieval for agents
- ✅ **Security**: Moved API keys to environment variables
- ✅ **Code Quality**: Consolidated duplicate code and improved error handling
- ✅ **Data Structures**: Standardized component storage with Dict-based approach
- ✅ **Validation**: Added comprehensive configuration validation
- ✅ **Error Handling**: Implemented consistent exception management throughout
Raw data
{
"_id": null,
"home_page": null,
"name": "ai-context-manager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "AI Context Manager Team <team@ai-context-manager.com>",
"keywords": "ai, context-management, vector-database, agents, llm, embeddings, postgresql, pgvector, chromadb, semantic-search, memory-management",
"author": null,
"author_email": "AI Context Manager Team <team@ai-context-manager.com>",
"download_url": "https://files.pythonhosted.org/packages/4c/8a/3aad9adc44960c81d1c59e730081a74085544433c784362525820c257426/ai_context_manager-0.2.0.tar.gz",
"platform": null,
"description": "# AI Context Manager\n\nA modular context management system for AI-powered applications with intelligent summarization and feedback learning.\n\n## Features\n\n- **Modular Architecture**: Pluggable components, stores, and summarizers\n- **Token-Aware Budgeting**: Intelligent context management with automatic summarization\n- **Feedback Learning**: Time-weighted scoring system for component prioritization\n- **Multiple Storage Backends**: JSON and SQLite support\n- **Privacy-Focused**: Local LLM support via Ollama\n- **Flexible Summarization**: OpenAI, Ollama, and naive summarizers\n\n## Quick Start\n\n### 1. Install Dependencies\n\n**Basic Installation:**\n```bash\npip install -e .\n```\n\n**With ChromaDB Support (Development):**\n```bash\npip install -e .[vector]\n```\n\n**With PostgreSQL Support (Production):**\n```bash\npip install -e .[production]\n```\n\n**Full Installation (All Features):**\n```bash\npip install -e .[all]\n```\n\n### 2. Set Up Environment Variables\n\nCopy `env.example` to `.env` and configure:\n\n```bash\ncp env.example .env\n```\n\nEdit `.env` with your settings:\n\n```env\n# Required for OpenAI summarizer\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Optional Ollama configuration\nOLLAMA_HOST=http://localhost:11434\nOLLAMA_MODEL=mistral\n```\n\n### 3. Configure the System\n\nEdit `config.toml` based on your setup:\n\n**For production agents (PostgreSQL + pgvector):**\n```toml\n[summarizer]\ntype = \"auto_fallback\" # Tries Ollama, falls back to naive\nmodel = \"mistral\"\n\n[feedback_store]\ntype = \"sqlite\"\ndb_path = \"feedback.db\"\n\n[memory_store]\ntype = \"postgres_vector\" # Enterprise-grade vector database\nhost = \"localhost\"\nport = 5432\ndatabase = \"ai_context\"\nuser = \"postgres\"\npassword = \"your_password\"\ntable_name = \"agent_memory\"\nembedding_dimension = 384\nindex_type = \"hnsw\"\n```\n\n**For development agents (ChromaDB):**\n```toml\n[summarizer]\ntype = \"auto_fallback\" # Tries Ollama, falls back to naive\nmodel = \"mistral\"\n\n[feedback_store]\ntype = \"json\"\nfilepath = \"feedback.json\"\n\n[memory_store]\ntype = \"vector\" # ChromaDB semantic similarity search\ncollection_name = \"agent_memory\"\npersist_directory = \"./chroma_db\"\nembedding_model = \"all-MiniLM-L6-v2\"\n```\n\n**For automatic fallback (simpler setup):**\n```toml\n[summarizer]\ntype = \"auto_fallback\" # Tries Ollama, falls back to naive\nmodel = \"mistral\"\n\n[feedback_store]\ntype = \"json\"\nfilepath = \"feedback.json\"\n\n[memory_store]\ntype = \"json\"\nfilepath = \"memory.json\"\n```\n\n**For local development (no external dependencies):**\n```toml\n[summarizer]\ntype = \"naive\" # Simple truncation, works anywhere\n\n[feedback_store]\ntype = \"json\"\nfilepath = \"feedback.json\"\n\n[memory_store]\ntype = \"json\"\nfilepath = \"memory.json\"\n```\n\n**When on your local network with Ollama:**\n```toml\n[summarizer]\ntype = \"ollama\"\nmodel = \"mistral\"\n# host will be read from OLLAMA_HOST environment variable\n\n[feedback_store]\ntype = \"json\"\nfilepath = \"feedback.json\"\n\n[memory_store]\ntype = \"json\"\nfilepath = \"memory.json\"\n```\n\n**For OpenAI integration:**\n```toml\n[summarizer]\ntype = \"openai\"\nmodel = \"gpt-3.5-turbo\"\n# api_key will be read from OPENAI_API_KEY environment variable\n\n[feedback_store]\ntype = \"json\"\nfilepath = \"feedback.json\"\n\n[memory_store]\ntype = \"json\"\nfilepath = \"memory.json\"\n```\n\n### 4. Basic Usage\n\n```python\nfrom ai_context_manager import ContextManager, TaskSummaryComponent\nfrom ai_context_manager.config import Config\nfrom ai_context_manager.utils import load_stores_from_config, load_summarizer\n\n# Load configuration\nconfig = Config(\"config.toml\")\nfeedback_store, memory_store = load_stores_from_config(config.data)\n\n# Initialize context manager\nctx = ContextManager(\n feedback_store=feedback_store,\n memory_store=memory_store,\n summarizer=load_summarizer(config)\n)\n\n# Add a component\ntask = TaskSummaryComponent(\n id=\"task-001\",\n task_name=\"Example Task\",\n summary=\"This is an example task summary\",\n tags=[\"example\", \"demo\"]\n)\n\nctx.register_component(task)\n\n# Get context\ncontext = ctx.get_context(\n include_tags=[\"example\"],\n token_budget=500,\n summarize_if_needed=True\n)\n\nprint(context)\n```\n\n## Configuration\n\n### Summarizers\n\n- **auto_fallback**: **Recommended** - Tries Ollama first, falls back to naive (best of both worlds)\n- **naive**: Simple truncation (no external dependencies) - **works anywhere**\n- **ollama**: Local LLM via Ollama API (requires local Ollama instance)\n- **openai**: OpenAI GPT models (requires API key and internet)\n\n### Storage\n\n- **JSON**: File-based storage for simple deployments\n- **SQLite**: Database storage for production use\n- **Vector**: ChromaDB-based semantic similarity search (development)\n- **PostgreSQL + pgvector**: Enterprise-grade vector database (production)\n\n### Network Scenarios\n\n**Automatic Fallback (Recommended):**\n- Use `type = \"auto_fallback\"` in config.toml\n- Automatically tries Ollama when available, falls back to naive when not\n- Perfect for switching between networks\n- Set `OLLAMA_HOST=http://192.168.0.156:11434` in .env for your network\n\n**Offline/Local Development:**\n- Use `type = \"naive\"` in config.toml\n- No external dependencies required\n- Perfect for development and testing\n\n**On Your Local Network:**\n- Set `type = \"ollama\"` in config.toml\n- Set `OLLAMA_HOST=http://192.168.0.156:11434` in .env\n- Requires Ollama running on your local network\n\n**Internet Access:**\n- Set `type = \"openai\"` in config.toml\n- Set `OPENAI_API_KEY=your_key` in .env\n- Requires OpenAI API access\n\n## Security\n\n- API keys are loaded from environment variables\n- No sensitive data is stored in configuration files\n- Local-first approach with Ollama support\n\n## Running Tests\n\n```bash\npython test_runner.py\n```\n\n## CLI Usage\n\nThe AI Context Manager includes a command-line interface for easy management:\n\n```bash\n# Initialize a new project\nai-context init\n\n# Show system status\nai-context status\n\n# Search for content\nai-context search \"AI trends\"\n\n# Get context for a query\nai-context context \"research findings\"\n\n# Add content\nai-context add task --id t1 --name \"Research\" --content \"Found insights\"\nai-context add learning --id l1 --content \"Vector DBs are faster\" --source \"testing\"\n\n# Manage configuration\nai-context config show\nai-context config optimize --use-case agent\n```\n\n## Performance Benchmarking\n\nRun performance benchmarks to test your system:\n\n```bash\npython benchmark_performance.py\n```\n\n## Quick Examples\n\nTry the quick start examples:\n\n```bash\npython examples/quick_start.py\n```\n\n## Architecture\n\n```\nai_context_manager/\n\u251c\u2500\u2500 components/ # Context component types\n\u251c\u2500\u2500 store/ # Storage backends\n\u251c\u2500\u2500 summarizers/ # Summarization engines\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 context_manager.py # Main context manager\n\u251c\u2500\u2500 feedback.py # Feedback learning system\n\u2514\u2500\u2500 utils.py # Utility functions\n```\n\n## Vector Database Benefits\n\n**Development (ChromaDB):**\n- \u2705 **Easy setup** - No database server required\n- \u2705 **Fast prototyping** - Perfect for local development\n- \u2705 **Semantic search** - Natural language queries\n- \u2705 **Lightweight** - Minimal dependencies\n\n**Production (PostgreSQL + pgvector):**\n- \u2705 **Enterprise-grade** - ACID transactions, backup/recovery\n- \u2705 **Horizontal scaling** - Read replicas, connection pooling\n- \u2705 **Advanced indexing** - HNSW/IVFFlat for sub-millisecond queries\n- \u2705 **Full-text search** - Combined with vector similarity\n- \u2705 **Monitoring** - Built-in observability and metrics\n\n**Performance:**\n- \ud83d\ude80 **10x faster** than traditional keyword search\n- \ud83d\ude80 **Sub-millisecond** vector similarity queries\n- \ud83d\ude80 **Concurrent access** with connection pooling\n- \ud83d\ude80 **Memory efficient** with advanced indexing\n\n**Installation:**\n```bash\n# Development\npip install ai-context-manager[vector]\n\n# Production\npip install ai-context-manager[production]\n```\n\n## Recent Improvements\n\n- \u2705 **PostgreSQL + pgvector**: Added enterprise-grade vector database support\n- \u2705 **Production Setup**: Complete production deployment guide\n- \u2705 **Vector Database**: Added ChromaDB-based semantic similarity search\n- \u2705 **Semantic Context Manager**: Enhanced context retrieval for agents\n- \u2705 **Security**: Moved API keys to environment variables\n- \u2705 **Code Quality**: Consolidated duplicate code and improved error handling\n- \u2705 **Data Structures**: Standardized component storage with Dict-based approach\n- \u2705 **Validation**: Added comprehensive configuration validation\n- \u2705 **Error Handling**: Implemented consistent exception management throughout\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enterprise-grade context management system for AI agents with vector database support",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/ai-context-manager/ai-context-manager/blob/main/CHANGELOG.md",
"Documentation": "https://docs.ai-context-manager.com",
"Homepage": "https://github.com/ai-context-manager/ai-context-manager",
"Issues": "https://github.com/ai-context-manager/ai-context-manager/issues",
"Repository": "https://github.com/ai-context-manager/ai-context-manager"
},
"split_keywords": [
"ai",
" context-management",
" vector-database",
" agents",
" llm",
" embeddings",
" postgresql",
" pgvector",
" chromadb",
" semantic-search",
" memory-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "70480f4927ffdd368465b0a2deb8cbb78b413518566586d839854319e1ee1171",
"md5": "df86c0f58f580cafef8840555c8d4d2f",
"sha256": "00e1b5854df4785abf5934f3a444bef78f0e9553d5b5475071dbafdb9ea8c129"
},
"downloads": -1,
"filename": "ai_context_manager-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df86c0f58f580cafef8840555c8d4d2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 51889,
"upload_time": "2025-10-06T22:04:55",
"upload_time_iso_8601": "2025-10-06T22:04:55.634327Z",
"url": "https://files.pythonhosted.org/packages/70/48/0f4927ffdd368465b0a2deb8cbb78b413518566586d839854319e1ee1171/ai_context_manager-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4c8a3aad9adc44960c81d1c59e730081a74085544433c784362525820c257426",
"md5": "59f17a728ca5211c75e989c8a2095a31",
"sha256": "1aa5899b8397d32061fdbc91df6967962f19d9d74d29482386d6b556689dfa9f"
},
"downloads": -1,
"filename": "ai_context_manager-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "59f17a728ca5211c75e989c8a2095a31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 44431,
"upload_time": "2025-10-06T22:04:57",
"upload_time_iso_8601": "2025-10-06T22:04:57.085797Z",
"url": "https://files.pythonhosted.org/packages/4c/8a/3aad9adc44960c81d1c59e730081a74085544433c784362525820c257426/ai_context_manager-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 22:04:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ai-context-manager",
"github_project": "ai-context-manager",
"github_not_found": true,
"lcname": "ai-context-manager"
}
JSON
