Agrama is a local micro-stack for knowledge management and retrieval, combining key-value storage, vector search, and LLM-powered summarization in a single, easy-to-deploy package.
Agrama provides a comprehensive solution for storing, retrieving, and analyzing structured and unstructured data with:
- Valkey 8.1 for key-value storage and graph relationships
- Faiss 1.11 for high-performance vector search
- Ollama running
qwen3:1.7bfor text summarization - FastAPI MCP server for API access
- Textual-based TUI for interactive exploration
Get sub-millisecond direct lookups, <50ms semantic search, and a simple deployment experience with docker compose up.
- Graph-based Knowledge Storage: Store nodes and relationships with efficient key schema
- Vector Search: Semantic search capabilities with Faiss
- Text Summarization: LLM-powered summarization of content
- MCP Protocol Support: Compatible with the Model Context Protocol
- Interactive TUI: Explore your knowledge graph with a terminal UI
- High Performance: Sub-millisecond lookups and fast semantic search
- Easy Deployment: Simple Docker Compose setup
- Docker and Docker Compose
- Python 3.10+
Clone the repository:
git clone https://github.com/yourusername/agrama.git cd agramaStart the services:
docker compose up -d
Install Python dependencies:
pip install -r requirements.txt
Launch the TUI:
agrama tui
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate# Install dependencies
pip install -r requirements.txt
# Install pre-commit hooks
pre-commit installThe project documentation is built using MkDocs with the Material theme. To work with the documentation:
# Install documentation dependencies
pip install -r requirements.txt
# Serve the documentation locally
mkdocs serve
# Build the documentation
mkdocs buildThe documentation is available at https://yourusername.github.io/agrama/ or locally at http://127.0.0.1:8000/ when running mkdocs serve.
# Start development containers
make dev
# Load sample data
make seed
# Run tests
make test# Run benchmarks
make bench
# Run load tests
make load
# Generate protocol buffers
make proto| Method | Path | Description |
|---|---|---|
PUT | /nodes | Create or update a node |
GET | /nodes/{uuid} | Get a node by UUID |
GET | /nodes/{uuid}/at/{ts} | Get a node at a specific time |
PUT | /edges | Create an edge between nodes |
GET | /edges/{src} | Get edges from a source node |
POST | /semantic_search | Search nodes by vector similarity |
GET | /keyword_search | Search nodes by keywords |
POST | /summarise | Generate a summary for a subgraph |
The MCP proxy endpoints (/v1/tools, /v1/resources, /v1/prompts) translate AAP calls to the MCP schema.
Agrama follows a modular architecture with the following components:
- API Layer: FastAPI-based REST API with AAP and MCP endpoints
- Database Layer: Valkey client (valkey-py) and graph helpers
- Vector Search: Faiss wrapper for embedding storage and retrieval
- Summarization: Ollama client for LLM-powered summarization
- TUI: Textual-based terminal user interface
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
All rights reserved. See LICENSE for more information.