# RAG Memory
[](https://pypi.org/project/rag-memory/)
[](https://pypi.org/project/rag-memory/)
[](https://opensource.org/licenses/MIT)
A production-ready **PostgreSQL + pgvector + Neo4j** knowledge management system with dual storage for semantic search (RAG) and knowledge graphs. Works as an **MCP server for AI agents** and a **standalone CLI tool**.
## ⚡ Quick Start (30 minutes)
Open a new terminal and run:
```bash
git clone https://github.com/yourusername/rag-memory.git
cd rag-memory
python scripts/setup.py
```
This setup script will:
- ✅ Check you have Docker installed
- ✅ Start PostgreSQL and Neo4j containers
- ✅ Ask for your OpenAI API key
- ✅ Initialize your local knowledge base
- ✅ Install the `rag` CLI tool
**That's it!** After setup completes, you'll have a working RAG Memory system ready to use.
---
## What Is This?
RAG Memory combines two powerful databases for knowledge management:
- **PostgreSQL + pgvector** - Semantic search across document content (RAG layer)
- **Neo4j** - Entity relationships and knowledge graphs (KG layer)
Both databases work together automatically - when you ingest a document, it's indexed in both systems simultaneously.
**Two ways to use it:**
1. **MCP Server** - Connect AI agents (Claude Desktop, Claude Code, Cursor) with 17 MCP tools
2. **CLI Tool** - Direct command-line access for testing, automation, and bulk operations
**Key capabilities:**
- Semantic search with vector embeddings (pgvector + HNSW indexing)
- Knowledge graph queries for relationships and entities
- Web crawling and documentation ingestion
- Document chunking for large files
- Collection management for organizing knowledge
- Full document lifecycle (create, read, update, delete)
- Cross-platform configuration system
**📚 Complete Documentation:** See [`.reference/`](./.reference/) directory for comprehensive guides (setup, MCP tools, pricing, search optimization, knowledge graphs)
### For Developers (Code Modifications)
If you want to modify the code:
```bash
# Clone repository
git clone https://github.com/yourusername/rag-memory.git
cd rag-memory
# Install dependencies
uv sync
# Copy environment template
cp .env.example .env
# Edit .env with your OPENAI_API_KEY
# Run tests or development commands
uv run pytest
uv run rag status
```
## CLI Commands
### Database & Status
```bash
rag status # Check database connection and stats
```
### Collection Management
```bash
rag collection create <name> --description TEXT # Description now required
rag collection list
rag collection info <name> # View stats and crawl history
rag collection update <name> --description TEXT # Update collection description
rag collection delete <name>
```
### Document Ingestion
**Text:**
```bash
rag ingest text "content" --collection <name> [--metadata JSON]
```
**Files:**
```bash
rag ingest file <path> --collection <name>
rag ingest directory <path> --collection <name> --extensions .txt,.md [--recursive]
```
**Web Pages:**
```bash
# Analyze website structure first
rag analyze https://docs.example.com
# Crawl single page
rag ingest url https://docs.example.com --collection docs
# Crawl with link following
rag ingest url https://docs.example.com --collection docs --follow-links --max-depth 2
# Re-crawl to update content
rag recrawl https://docs.example.com --collection docs --follow-links --max-depth 2
```
### Search
**⚠️ IMPORTANT: Use Natural Language, Not Keywords**
This system uses **semantic similarity search**, not keyword matching. Always use complete questions or sentences:
- ✅ Good: `"How do I configure authentication in the system?"`
- ❌ Bad: `"authentication configuration"`
```bash
# Basic search
rag search "How do I configure authentication?" --collection <name>
# Advanced options
rag search "What are the best practices for error handling?" --collection <name> --limit 10 --threshold 0.7 --verbose --show-source
# Search with metadata filter
rag search "How do I use decorators in Python?" --metadata '{"topic":"python"}'
```
### Document Management
```bash
# List documents
rag document list [--collection <name>]
# View document details
rag document view <ID> [--show-chunks] [--show-content]
# Update document (re-chunks and re-embeds)
rag document update <ID> --content "new content" [--title "title"] [--metadata JSON]
# Delete document
rag document delete <ID> [--confirm]
```
## MCP Server for AI Agents
RAG Memory exposes 17 tools via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for AI agent integration.
### Quick Setup
**1. Run the setup script:**
```bash
git clone https://github.com/yourusername/rag-memory.git
cd rag-memory
python scripts/setup.py
```
After setup, RAG Memory's MCP server is automatically running in Docker on port 8000.
**2. Connect to Claude Code:**
```bash
claude mcp add rag-memory --type sse --url http://localhost:8000/sse
```
**3. Connect to Claude Desktop** (optional):
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"rag-memory": {
"command": "rag-mcp-stdio",
"args": []
}
}
}
```
Then restart Claude Desktop.
**4. Test:** Ask your agent "List RAG Memory collections"
### Available MCP Tools (17 Total)
**Core RAG (3 tools):**
- `search_documents` - Semantic search across knowledge base
- `list_collections` - Discover available collections
- `ingest_text` - Add text content with auto-chunking
**Collection Management (2 tools):**
- `create_collection` - Create new collections (description required)
- `update_collection_description` - Update existing collection descriptions
**Document Management (4 tools):**
- `list_documents` - Browse documents with pagination
- `get_document_by_id` - Retrieve full source document
- `update_document` - Edit existing documents (triggers re-chunking/re-embedding)
- `delete_document` - Remove outdated documents
**Advanced Ingestion (5 tools):**
- `get_collection_info` - Collection stats and crawl history
- `analyze_website` - Sitemap analysis for planning crawls
- `ingest_url` - Crawl web pages with duplicate prevention (crawl/recrawl modes)
- `ingest_file` - Ingest from file system
- `ingest_directory` - Batch ingest from directories
See [docs/MCP_SERVER_GUIDE.md](./docs/MCP_SERVER_GUIDE.md) for complete tool reference and examples.
## Configuration System
RAG Memory uses a three-tier priority system for configuration:
1. **Environment variables** (highest priority) - Set in your shell
2. **Project `.env` file** (current directory only) - For developers
3. **Global `~/.rag-memory-env`** (lowest priority) - For end users
**For CLI usage:** First run triggers interactive setup wizard
**For MCP server:** Configuration comes from MCP client config (not files)
See [docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md) for complete details.
## Key Features
### Vector Search with pgvector
- PostgreSQL 17 + pgvector extension
- HNSW indexing for fast approximate nearest neighbor search
- Vector normalization for accurate cosine similarity
- Optimized for 95%+ recall
### Document Chunking
- Hierarchical text splitting (headers → paragraphs → sentences)
- ~1000 chars per chunk with 200 char overlap
- Preserves context across boundaries
- Each chunk independently embedded and searchable
- Source documents preserved for full context retrieval
### Web Crawling
- Built on Crawl4AI for robust web scraping
- Sitemap.xml parsing for comprehensive crawls
- Follow internal links with configurable depth
- Duplicate prevention (crawl mode vs recrawl mode)
- Crawl metadata tracking (root URL, session ID, timestamp)
### Collection Management
- Organize documents by topic/domain
- Many-to-many relationships (documents can belong to multiple collections)
- Search can be scoped to specific collection
- Collection statistics and crawl history
- Required descriptions for better organization (enforced by database constraint)
### Full Document Lifecycle
- Create: Ingest from text, files, directories, URLs
- Read: Search chunks, retrieve full documents
- Update: Edit content with automatic re-chunking/re-embedding
- Delete: Remove outdated documents and their chunks
## Architecture
### Database Schema
**Source documents and chunks:**
- `source_documents` - Full original documents
- `document_chunks` - Searchable chunks with embeddings (vector[1536])
- `collections` - Named groupings (description required with NOT NULL constraint)
- `chunk_collections` - Junction table (N:M relationship)
**Indexes:**
- HNSW on `document_chunks.embedding` for fast vector search
- GIN on metadata columns for efficient JSONB queries
**Migrations:**
- Managed by Alembic (see `docs/DATABASE_MIGRATION_GUIDE.md`)
- Version tracking in `alembic_version` table
- Run migrations: `uv run rag migrate`
### Python Application
```
src/
├── cli.py # Command-line interface
├── core/
│ ├── config_loader.py # Three-tier environment configuration
│ ├── first_run.py # Interactive setup wizard
│ ├── database.py # PostgreSQL connection management
│ ├── embeddings.py # OpenAI embeddings with normalization
│ ├── collections.py # Collection CRUD operations
│ └── chunking.py # Document text splitting
├── ingestion/
│ ├── document_store.py # High-level document management
│ ├── web_crawler.py # Web page crawling (Crawl4AI)
│ └── website_analyzer.py # Sitemap analysis
├── retrieval/
│ └── search.py # Semantic search with pgvector
└── mcp/
├── server.py # MCP server (FastMCP)
└── tools.py # 14 MCP tool implementations
```
## Documentation
- **[.reference/OVERVIEW.md](./.reference/OVERVIEW.md)** - Quick overview for slash command
- **[.reference/MCP_QUICK_START.md](./.reference/MCP_QUICK_START.md)** - MCP setup guide
- **[docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md)** - Configuration system explained
- **[docs/MCP_SERVER_GUIDE.md](./docs/MCP_SERVER_GUIDE.md)** - Complete MCP tool reference (14 tools)
- **[docs/DATABASE_MIGRATION_GUIDE.md](./docs/DATABASE_MIGRATION_GUIDE.md)** - Database schema migration guide (Alembic)
- **[CLAUDE.md](./CLAUDE.md)** - Development guide and CLI reference
## Prerequisites
- **Docker & Docker Compose** - For PostgreSQL database
- **uv** - Fast Python package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
- **Python 3.12+** - Managed by uv
- **OpenAI API Key** - For embedding generation (https://platform.openai.com/api-keys)
## Technology Stack
- **Database:** PostgreSQL 17 + pgvector extension
- **Language:** Python 3.12
- **Package Manager:** uv (Astral)
- **Embedding Model:** OpenAI text-embedding-3-small (1536 dims)
- **Web Crawling:** Crawl4AI (Playwright-based)
- **MCP Server:** FastMCP (Anthropic)
- **CLI Framework:** Click + Rich
- **Testing:** pytest
## Cost Analysis
**OpenAI text-embedding-3-small:** $0.02 per 1M tokens
Example usage:
- 10,000 documents × 750 tokens avg = 7.5M tokens
- One-time embedding cost: **$0.15**
- Per-query cost: ~$0.00003 (negligible)
Extremely cost-effective for most use cases.
## Development
### Running Tests
```bash
uv run pytest # All tests
uv run pytest tests/test_embeddings.py # Specific file
```
### Code Quality
```bash
uv run black src/ tests/ # Format
uv run ruff check src/ tests/ # Lint
```
## Troubleshooting
### Database connection errors
```bash
docker-compose ps # Check if running
docker-compose logs postgres # View logs
docker-compose restart # Restart
docker-compose down -v && docker-compose up -d # Reset
```
### Configuration issues
```bash
# Check global config
cat ~/.rag-memory-env
# Re-run first-run wizard
rm ~/.rag-memory-env
rag status
# Check environment variables
env | grep -E '(DATABASE_URL|OPENAI_API_KEY)'
```
### MCP server not showing in agent
- Check JSON syntax in MCP config (no trailing commas!)
- Verify both DATABASE_URL and OPENAI_API_KEY in `env` section
- Check MCP logs: `~/Library/Logs/Claude/mcp*.log` (macOS)
- Restart AI agent completely (quit and reopen)
See [docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md) troubleshooting section for more.
## License
MIT License - See LICENSE file for details.
## Support
**For help getting started:**
- Run `/getting-started` slash command in Claude Code
- Read [.reference/OVERVIEW.md](./.reference/OVERVIEW.md)
- Check [docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md)
**For MCP server setup:**
- See [.reference/MCP_QUICK_START.md](./.reference/MCP_QUICK_START.md)
- Read [docs/MCP_SERVER_GUIDE.md](./docs/MCP_SERVER_GUIDE.md)
**For issues:**
- Check troubleshooting sections above
- Review documentation in docs/ directory
- Check database logs: `docker-compose logs -f`
---
**Built with PostgreSQL + pgvector for production-grade semantic search.**
Raw data
{
"_id": null,
"home_page": null,
"name": "rag-memory",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, embeddings, mcp, pgvector, postgresql, rag, vector-database",
"author": "Tim Kitchens",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/68/dc/88dc6a5dc70db49e4d1bd6584c3f127e1da9c7ab89dbab22a0c2932d6b8a/rag_memory-0.19.0.tar.gz",
"platform": null,
"description": "# RAG Memory\n\n[](https://pypi.org/project/rag-memory/)\n[](https://pypi.org/project/rag-memory/)\n[](https://opensource.org/licenses/MIT)\n\nA production-ready **PostgreSQL + pgvector + Neo4j** knowledge management system with dual storage for semantic search (RAG) and knowledge graphs. Works as an **MCP server for AI agents** and a **standalone CLI tool**.\n\n## \u26a1 Quick Start (30 minutes)\n\nOpen a new terminal and run:\n\n```bash\ngit clone https://github.com/yourusername/rag-memory.git\ncd rag-memory\npython scripts/setup.py\n```\n\nThis setup script will:\n- \u2705 Check you have Docker installed\n- \u2705 Start PostgreSQL and Neo4j containers\n- \u2705 Ask for your OpenAI API key\n- \u2705 Initialize your local knowledge base\n- \u2705 Install the `rag` CLI tool\n\n**That's it!** After setup completes, you'll have a working RAG Memory system ready to use.\n\n---\n\n## What Is This?\n\nRAG Memory combines two powerful databases for knowledge management:\n\n- **PostgreSQL + pgvector** - Semantic search across document content (RAG layer)\n- **Neo4j** - Entity relationships and knowledge graphs (KG layer)\n\nBoth databases work together automatically - when you ingest a document, it's indexed in both systems simultaneously.\n\n**Two ways to use it:**\n1. **MCP Server** - Connect AI agents (Claude Desktop, Claude Code, Cursor) with 17 MCP tools\n2. **CLI Tool** - Direct command-line access for testing, automation, and bulk operations\n\n**Key capabilities:**\n- Semantic search with vector embeddings (pgvector + HNSW indexing)\n- Knowledge graph queries for relationships and entities\n- Web crawling and documentation ingestion\n- Document chunking for large files\n- Collection management for organizing knowledge\n- Full document lifecycle (create, read, update, delete)\n- Cross-platform configuration system\n\n**\ud83d\udcda Complete Documentation:** See [`.reference/`](./.reference/) directory for comprehensive guides (setup, MCP tools, pricing, search optimization, knowledge graphs)\n\n### For Developers (Code Modifications)\n\nIf you want to modify the code:\n\n```bash\n# Clone repository\ngit clone https://github.com/yourusername/rag-memory.git\ncd rag-memory\n\n# Install dependencies\nuv sync\n\n# Copy environment template\ncp .env.example .env\n# Edit .env with your OPENAI_API_KEY\n\n# Run tests or development commands\nuv run pytest\nuv run rag status\n```\n\n## CLI Commands\n\n### Database & Status\n```bash\nrag status # Check database connection and stats\n```\n\n### Collection Management\n```bash\nrag collection create <name> --description TEXT # Description now required\nrag collection list\nrag collection info <name> # View stats and crawl history\nrag collection update <name> --description TEXT # Update collection description\nrag collection delete <name>\n```\n\n### Document Ingestion\n\n**Text:**\n```bash\nrag ingest text \"content\" --collection <name> [--metadata JSON]\n```\n\n**Files:**\n```bash\nrag ingest file <path> --collection <name>\nrag ingest directory <path> --collection <name> --extensions .txt,.md [--recursive]\n```\n\n**Web Pages:**\n```bash\n# Analyze website structure first\nrag analyze https://docs.example.com\n\n# Crawl single page\nrag ingest url https://docs.example.com --collection docs\n\n# Crawl with link following\nrag ingest url https://docs.example.com --collection docs --follow-links --max-depth 2\n\n# Re-crawl to update content\nrag recrawl https://docs.example.com --collection docs --follow-links --max-depth 2\n```\n\n### Search\n\n**\u26a0\ufe0f IMPORTANT: Use Natural Language, Not Keywords**\nThis system uses **semantic similarity search**, not keyword matching. Always use complete questions or sentences:\n- \u2705 Good: `\"How do I configure authentication in the system?\"`\n- \u274c Bad: `\"authentication configuration\"`\n\n```bash\n# Basic search\nrag search \"How do I configure authentication?\" --collection <name>\n\n# Advanced options\nrag search \"What are the best practices for error handling?\" --collection <name> --limit 10 --threshold 0.7 --verbose --show-source\n\n# Search with metadata filter\nrag search \"How do I use decorators in Python?\" --metadata '{\"topic\":\"python\"}'\n```\n\n### Document Management\n```bash\n# List documents\nrag document list [--collection <name>]\n\n# View document details\nrag document view <ID> [--show-chunks] [--show-content]\n\n# Update document (re-chunks and re-embeds)\nrag document update <ID> --content \"new content\" [--title \"title\"] [--metadata JSON]\n\n# Delete document\nrag document delete <ID> [--confirm]\n```\n\n## MCP Server for AI Agents\n\nRAG Memory exposes 17 tools via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for AI agent integration.\n\n### Quick Setup\n\n**1. Run the setup script:**\n```bash\ngit clone https://github.com/yourusername/rag-memory.git\ncd rag-memory\npython scripts/setup.py\n```\n\nAfter setup, RAG Memory's MCP server is automatically running in Docker on port 8000.\n\n**2. Connect to Claude Code:**\n```bash\nclaude mcp add rag-memory --type sse --url http://localhost:8000/sse\n```\n\n**3. Connect to Claude Desktop** (optional):\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n```json\n{\n \"mcpServers\": {\n \"rag-memory\": {\n \"command\": \"rag-mcp-stdio\",\n \"args\": []\n }\n }\n}\n```\n\nThen restart Claude Desktop.\n\n**4. Test:** Ask your agent \"List RAG Memory collections\"\n\n### Available MCP Tools (17 Total)\n\n**Core RAG (3 tools):**\n- `search_documents` - Semantic search across knowledge base\n- `list_collections` - Discover available collections\n- `ingest_text` - Add text content with auto-chunking\n\n**Collection Management (2 tools):**\n- `create_collection` - Create new collections (description required)\n- `update_collection_description` - Update existing collection descriptions\n\n**Document Management (4 tools):**\n- `list_documents` - Browse documents with pagination\n- `get_document_by_id` - Retrieve full source document\n- `update_document` - Edit existing documents (triggers re-chunking/re-embedding)\n- `delete_document` - Remove outdated documents\n\n**Advanced Ingestion (5 tools):**\n- `get_collection_info` - Collection stats and crawl history\n- `analyze_website` - Sitemap analysis for planning crawls\n- `ingest_url` - Crawl web pages with duplicate prevention (crawl/recrawl modes)\n- `ingest_file` - Ingest from file system\n- `ingest_directory` - Batch ingest from directories\n\nSee [docs/MCP_SERVER_GUIDE.md](./docs/MCP_SERVER_GUIDE.md) for complete tool reference and examples.\n\n## Configuration System\n\nRAG Memory uses a three-tier priority system for configuration:\n\n1. **Environment variables** (highest priority) - Set in your shell\n2. **Project `.env` file** (current directory only) - For developers\n3. **Global `~/.rag-memory-env`** (lowest priority) - For end users\n\n**For CLI usage:** First run triggers interactive setup wizard\n\n**For MCP server:** Configuration comes from MCP client config (not files)\n\nSee [docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md) for complete details.\n\n## Key Features\n\n### Vector Search with pgvector\n- PostgreSQL 17 + pgvector extension\n- HNSW indexing for fast approximate nearest neighbor search\n- Vector normalization for accurate cosine similarity\n- Optimized for 95%+ recall\n\n### Document Chunking\n- Hierarchical text splitting (headers \u2192 paragraphs \u2192 sentences)\n- ~1000 chars per chunk with 200 char overlap\n- Preserves context across boundaries\n- Each chunk independently embedded and searchable\n- Source documents preserved for full context retrieval\n\n### Web Crawling\n- Built on Crawl4AI for robust web scraping\n- Sitemap.xml parsing for comprehensive crawls\n- Follow internal links with configurable depth\n- Duplicate prevention (crawl mode vs recrawl mode)\n- Crawl metadata tracking (root URL, session ID, timestamp)\n\n### Collection Management\n- Organize documents by topic/domain\n- Many-to-many relationships (documents can belong to multiple collections)\n- Search can be scoped to specific collection\n- Collection statistics and crawl history\n- Required descriptions for better organization (enforced by database constraint)\n\n### Full Document Lifecycle\n- Create: Ingest from text, files, directories, URLs\n- Read: Search chunks, retrieve full documents\n- Update: Edit content with automatic re-chunking/re-embedding\n- Delete: Remove outdated documents and their chunks\n\n## Architecture\n\n### Database Schema\n\n**Source documents and chunks:**\n- `source_documents` - Full original documents\n- `document_chunks` - Searchable chunks with embeddings (vector[1536])\n- `collections` - Named groupings (description required with NOT NULL constraint)\n- `chunk_collections` - Junction table (N:M relationship)\n\n**Indexes:**\n- HNSW on `document_chunks.embedding` for fast vector search\n- GIN on metadata columns for efficient JSONB queries\n\n**Migrations:**\n- Managed by Alembic (see `docs/DATABASE_MIGRATION_GUIDE.md`)\n- Version tracking in `alembic_version` table\n- Run migrations: `uv run rag migrate`\n\n### Python Application\n\n```\nsrc/\n\u251c\u2500\u2500 cli.py # Command-line interface\n\u251c\u2500\u2500 core/\n\u2502 \u251c\u2500\u2500 config_loader.py # Three-tier environment configuration\n\u2502 \u251c\u2500\u2500 first_run.py # Interactive setup wizard\n\u2502 \u251c\u2500\u2500 database.py # PostgreSQL connection management\n\u2502 \u251c\u2500\u2500 embeddings.py # OpenAI embeddings with normalization\n\u2502 \u251c\u2500\u2500 collections.py # Collection CRUD operations\n\u2502 \u2514\u2500\u2500 chunking.py # Document text splitting\n\u251c\u2500\u2500 ingestion/\n\u2502 \u251c\u2500\u2500 document_store.py # High-level document management\n\u2502 \u251c\u2500\u2500 web_crawler.py # Web page crawling (Crawl4AI)\n\u2502 \u2514\u2500\u2500 website_analyzer.py # Sitemap analysis\n\u251c\u2500\u2500 retrieval/\n\u2502 \u2514\u2500\u2500 search.py # Semantic search with pgvector\n\u2514\u2500\u2500 mcp/\n \u251c\u2500\u2500 server.py # MCP server (FastMCP)\n \u2514\u2500\u2500 tools.py # 14 MCP tool implementations\n```\n\n## Documentation\n\n- **[.reference/OVERVIEW.md](./.reference/OVERVIEW.md)** - Quick overview for slash command\n- **[.reference/MCP_QUICK_START.md](./.reference/MCP_QUICK_START.md)** - MCP setup guide\n- **[docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md)** - Configuration system explained\n- **[docs/MCP_SERVER_GUIDE.md](./docs/MCP_SERVER_GUIDE.md)** - Complete MCP tool reference (14 tools)\n- **[docs/DATABASE_MIGRATION_GUIDE.md](./docs/DATABASE_MIGRATION_GUIDE.md)** - Database schema migration guide (Alembic)\n- **[CLAUDE.md](./CLAUDE.md)** - Development guide and CLI reference\n\n## Prerequisites\n\n- **Docker & Docker Compose** - For PostgreSQL database\n- **uv** - Fast Python package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`)\n- **Python 3.12+** - Managed by uv\n- **OpenAI API Key** - For embedding generation (https://platform.openai.com/api-keys)\n\n## Technology Stack\n\n- **Database:** PostgreSQL 17 + pgvector extension\n- **Language:** Python 3.12\n- **Package Manager:** uv (Astral)\n- **Embedding Model:** OpenAI text-embedding-3-small (1536 dims)\n- **Web Crawling:** Crawl4AI (Playwright-based)\n- **MCP Server:** FastMCP (Anthropic)\n- **CLI Framework:** Click + Rich\n- **Testing:** pytest\n\n## Cost Analysis\n\n**OpenAI text-embedding-3-small:** $0.02 per 1M tokens\n\nExample usage:\n- 10,000 documents \u00d7 750 tokens avg = 7.5M tokens\n- One-time embedding cost: **$0.15**\n- Per-query cost: ~$0.00003 (negligible)\n\nExtremely cost-effective for most use cases.\n\n## Development\n\n### Running Tests\n```bash\nuv run pytest # All tests\nuv run pytest tests/test_embeddings.py # Specific file\n```\n\n### Code Quality\n```bash\nuv run black src/ tests/ # Format\nuv run ruff check src/ tests/ # Lint\n```\n\n## Troubleshooting\n\n### Database connection errors\n```bash\ndocker-compose ps # Check if running\ndocker-compose logs postgres # View logs\ndocker-compose restart # Restart\ndocker-compose down -v && docker-compose up -d # Reset\n```\n\n### Configuration issues\n```bash\n# Check global config\ncat ~/.rag-memory-env\n\n# Re-run first-run wizard\nrm ~/.rag-memory-env\nrag status\n\n# Check environment variables\nenv | grep -E '(DATABASE_URL|OPENAI_API_KEY)'\n```\n\n### MCP server not showing in agent\n- Check JSON syntax in MCP config (no trailing commas!)\n- Verify both DATABASE_URL and OPENAI_API_KEY in `env` section\n- Check MCP logs: `~/Library/Logs/Claude/mcp*.log` (macOS)\n- Restart AI agent completely (quit and reopen)\n\nSee [docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md) troubleshooting section for more.\n\n## License\n\nMIT License - See LICENSE file for details.\n\n## Support\n\n**For help getting started:**\n- Run `/getting-started` slash command in Claude Code\n- Read [.reference/OVERVIEW.md](./.reference/OVERVIEW.md)\n- Check [docs/ENVIRONMENT_VARIABLES.md](./docs/ENVIRONMENT_VARIABLES.md)\n\n**For MCP server setup:**\n- See [.reference/MCP_QUICK_START.md](./.reference/MCP_QUICK_START.md)\n- Read [docs/MCP_SERVER_GUIDE.md](./docs/MCP_SERVER_GUIDE.md)\n\n**For issues:**\n- Check troubleshooting sections above\n- Review documentation in docs/ directory\n- Check database logs: `docker-compose logs -f`\n\n---\n\n**Built with PostgreSQL + pgvector for production-grade semantic search.**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PostgreSQL pgvector-based RAG memory system with MCP server",
"version": "0.19.0",
"project_urls": null,
"split_keywords": [
"ai",
" embeddings",
" mcp",
" pgvector",
" postgresql",
" rag",
" vector-database"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4698f1e7aa4c9d0bb3bf986c943c01b50ca31e06549af84aef377269e5cd8e0a",
"md5": "b31e6b4526fe869106c94405acca4198",
"sha256": "9ce7ffd2237f1b9197b566efb1a842175838e5cb19e12dd1c11f5e6d603952ba"
},
"downloads": -1,
"filename": "rag_memory-0.19.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b31e6b4526fe869106c94405acca4198",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 118840,
"upload_time": "2025-11-10T01:53:27",
"upload_time_iso_8601": "2025-11-10T01:53:27.558096Z",
"url": "https://files.pythonhosted.org/packages/46/98/f1e7aa4c9d0bb3bf986c943c01b50ca31e06549af84aef377269e5cd8e0a/rag_memory-0.19.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "68dc88dc6a5dc70db49e4d1bd6584c3f127e1da9c7ab89dbab22a0c2932d6b8a",
"md5": "86239d008c1ba5d0d2f74ec2067bc3b4",
"sha256": "738bf3de2637d8f03049d0d5aeb81d92f88f71b7acea337ffbdc0b578bc3f8a9"
},
"downloads": -1,
"filename": "rag_memory-0.19.0.tar.gz",
"has_sig": false,
"md5_digest": "86239d008c1ba5d0d2f74ec2067bc3b4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 303820,
"upload_time": "2025-11-10T01:53:29",
"upload_time_iso_8601": "2025-11-10T01:53:29.070297Z",
"url": "https://files.pythonhosted.org/packages/68/dc/88dc6a5dc70db49e4d1bd6584c3f127e1da9c7ab89dbab22a0c2932d6b8a/rag_memory-0.19.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-10 01:53:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "rag-memory"
}
JSON