memini-ai-dev 0.2.0__tar.gz

memini_ai_dev-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies (including dev)
+        run: uv sync --extra dev
+
+      - name: Check code formatting
+        run: uvx ruff format --check .
+
+      - name: Lint code
+        run: uvx ruff check .
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build

memini_ai_dev-0.2.0/.github/workflows/workflow.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Build package
+        run: uv build
+
+      - name: Extract tag name
+        id: extract_tag
+        run: echo "tag_name=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.extract_tag.outputs.tag_name }}
+          name: ${{ steps.extract_tag.outputs.tag_name }}
+          generate_release_notes: true
+          files: dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

memini_ai_dev-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+TASKS.md
+PHASE*_PLAN.md
+CONTEXT.md
+HANDOFF.md

memini_ai_dev-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

memini_ai_dev-0.2.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-18
+
+### Features
+
+- pgvector/pgvectorscale backend with StreamingDiskANN index
+- VectorDatabase ABC for database abstraction
+- PostgresDatabase class with asyncpg support
+- New `postgres/` module with schema and queries
+- Migration script: `scripts/migrate_qdrant_to_pgvector.py`
+- New config options: `MEMINI_DB_URL`, `db_pool_size`, `db_min_size`, `db_max_size`
+
+### Tests
+
+- 38 new tests for PostgresDatabase
+
+### Bug Fixes
+
+- N/A
+
+### Breaking Changes
+
+- None (backward compatible with Qdrant)

memini_ai_dev-0.2.0/PKG-INFO

@@ -0,0 +1,370 @@
+Metadata-Version: 2.4
+Name: memini-ai-dev
+Version: 0.2.0
+Summary: Local-first semantic memory server with vector search
+Project-URL: Homepage, https://github.com/Veedubin/memini-ai-dev
+Project-URL: Repository, https://github.com/Veedubin/memini-ai-dev
+Author: VeeDubin
+License: MIT
+Keywords: mcp,memory,qdrant,semantic-search,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: qdrant-client>=1.12
+Requires-Dist: rank-bm25>=0.2
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: tenacity>=8.0
+Requires-Dist: torch>=2.0
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Memini-ai v3.0
+
+> "I remember" in Latin (pronounced *meh-mee-nee*)
+
+Local-first semantic memory server with vector search, MCP-compatible.
+
+## Overview
+
+Memini-ai is a Python rewrite of [Super-Memory-TS](https://github.com/veedubin/super-memory-ts), designed as a local-first semantic memory server with vector search capabilities. It provides persistent memory storage and retrieval using Qdrant as the backend vector database.
+
+### Key Features
+
+- **MCP-Compatible**: Works with any MCP-compatible client (OpenCode, Claude Desktop, etc.)
+- **Vector Search**: BGE-Large embeddings (1024-dim) with MiniLM fallback (384-dim)
+- **Hybrid Search**: Combines vector similarity with BM25 text search
+- **Project Isolation**: Memories are isolated by project ID
+- **File Indexing**: Index and search project files with semantic chunking
+- **Graceful Degradation**: Works without Qdrant (returns errors for memory operations)
+- **CPU-First**: Designed to run on CPU, optional GPU acceleration
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11+
+- [Qdrant](https://qdrant.tech/documentation/guides/installation/) running locally or remotely
+
+### Quick Start
+
+```bash
+# Install memini-ai
+pip install memini-ai
+
+# Start Qdrant (if not running)
+docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
+
+# Run the server
+memini-ai --stdio
+```
+
+### Development Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/veedubin/memini-ai.git
+cd memini-ai
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# or: .venv\Scripts\activate  # Windows
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+Memini-ai can be configured via environment variables or a JSON config file.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEMINI_QDRANT_URL` | `http://localhost:6333` | Qdrant server URL |
+| `MEMINI_PROJECT_ID` | auto-generated | Project identifier for isolation |
+| `MEMINI_EMBEDDING_DIM` | `1024` | Embedding dimension (1024 or 384) |
+| `MEMINI_CHUNK_SIZE` | `512` | Chunk size for file indexing |
+| `MEMINI_CHUNK_OVERLAP` | `64` | Overlap between chunks |
+| `MEMINI_BATCH_SIZE` | `32` | Batch size for embedding generation |
+| `MEMINI_WORKERS` | `4` | Number of worker threads |
+| `MEMINI_LOG_LEVEL` | `INFO` | Logging level |
+| `MEMINI_CONFIG_PATH` | None | Path to JSON config file |
+
+### JSON Config File
+
+```json
+{
+  "qdrant": {
+    "url": "http://localhost:6333"
+  },
+  "model": {
+    "embedding_dim": 1024
+  },
+  "indexer": {
+    "chunk_size": 512,
+    "chunk_overlap": 64
+  },
+  "logging": {
+    "level": "INFO"
+  }
+}
+```
+
+## Usage
+
+### MCP Tools
+
+Memini-ai provides 6 MCP tools:
+
+#### `query_memories`
+Semantic search over memories.
+
+```json
+{
+  "query": "What files were modified yesterday?",
+  "limit": 10,
+  "strategy": "tiered"
+}
+```
+
+**Strategies:**
+- `tiered` (default): MiniLM primary + BGE fallback
+- `vector_only`: Pure semantic similarity
+- `text_only`: BM25 keyword search
+- `parallel`: Dual-tier with RRF fusion
+
+#### `add_memory`
+Store a new memory entry.
+
+```json
+{
+  "content": "Remember to update the config file",
+  "sourceType": "session",
+  "sourcePath": "/path/to/file",
+  "metadata": {"key": "value"}
+}
+```
+
+#### `search_project`
+Search indexed project files.
+
+```json
+{
+  "query": "authentication middleware",
+  "topK": 20,
+  "fileTypes": [".py", ".ts"],
+  "paths": ["src/"]
+}
+```
+
+#### `index_project`
+Trigger project indexing.
+
+```json
+{
+  "path": ".",
+  "force": false,
+  "background": true
+}
+```
+
+#### `get_file_contents`
+Reconstruct a file from indexed chunks.
+
+```json
+{
+  "filePath": "src/main.py",
+  "triggerIndex": false
+}
+```
+
+#### `get_status`
+Get server component status.
+
+```json
+{}
+```
+
+### Python API
+
+```python
+from memini_ai.memory.system import MemorySystem
+from memini_ai.memory.schema import MemoryEntry, MemorySourceType, SearchOptions, SearchStrategy
+
+async def main():
+    # Create and initialize
+    system = MemorySystem()
+    await system.initialize()
+
+    # Add a memory
+    entry = MemoryEntry(
+        text="Python list comprehension tutorial",
+        source_type=MemorySourceType.session,
+    )
+    memory_id = await system.add_memory(entry)
+
+    # Query memories
+    options = SearchOptions(topK=10, strategy=SearchStrategy.TIERED)
+    results = await system.query_memories("list comprehension", options)
+
+    # Delete memory
+    await system.delete_memory(memory_id)
+
+asyncio.run(main())
+```
+
+## Docker Compose
+
+For local development with Qdrant:
+
+```yaml
+version: '3.8'
+
+services:
+  qdrant:
+    image: qdrant/qdrant
+    ports:
+      - "6333:6333"
+      - "6334:6334"
+    volumes:
+      - qdrant_data:/qdrant/storage
+
+  memini-ai:
+    build: .
+    depends_on:
+      - qdrant
+    environment:
+      - MEMINI_QDRANT_URL=http://qdrant:6333
+    volumes:
+      - .:/app
+
+volumes:
+  qdrant_data:
+```
+
+```bash
+docker-compose up -d
+```
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run unit tests only (skip integration)
+pytest tests/ -v --ignore=tests/integration/
+
+# Run integration tests (requires Qdrant)
+pytest tests/integration/ -v
+
+# Run with coverage
+pytest tests/ --cov=src/memini_ai --cov-report=term-missing
+```
+
+### Integration Tests with Docker
+
+```bash
+# Start Qdrant for integration tests
+docker run -d --name qdrant-test -p 6333:6333 qdrant/qdrant
+
+# Run integration tests
+pytest tests/integration/ -v
+
+# Cleanup
+docker stop qdrant-test && docker rm qdrant-test
+```
+
+## Quality Gates
+
+Before submitting changes, ensure:
+
+```bash
+# Lint
+ruff check src/
+
+# Format
+ruff format src/
+
+# Type check
+mypy src/
+
+# Tests
+pytest tests/ -x
+```
+
+## Performance
+
+Memini-ai is designed for sub-10ms query latency on cached queries.
+
+Typical performance:
+- **Query latency**: < 10ms (after warmup)
+- **Indexing**: ~1000 files/second
+- **Memory footprint**: ~500MB (without model)
+
+### Performance Tuning
+
+```bash
+# Use faster embedding model (384-dim instead of 1024)
+export MEMINI_EMBEDDING_DIM=384
+
+# Increase workers for faster indexing
+export MEMINI_WORKERS=8
+
+# Larger batch size for embedding generation
+export MEMINI_BATCH_SIZE=64
+```
+
+## Architecture
+
+```
+memini_ai/
+├── config.py           # Configuration management
+├── server.py          # FastMCP server (6 tools)
+├── memory/
+│   ├── schema.py      # Pydantic models
+│   ├── database.py    # Qdrant CRUD operations
+│   ├── search.py      # 4 search strategies
+│   └── system.py      # MemorySystem coordinator
+├── model/
+│   ├── manager.py     # ModelManager singleton
+│   └── embeddings.py # Embedding generation
+├── indexer/
+│   ├── indexer.py     # ProjectIndexer
+│   ├── chunker.py     # Semantic chunking
+│   ├── watcher.py     # File watching
+│   └── file_tracker.py # SQLite persistence
+└── utils/
+    ├── logger.py     # Structured logging
+    └── hash.py       # SHA-256 utilities
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Links
+
+- [Repository](https://github.com/veedubin/memini-ai)
+- [Documentation](https://github.com/veedubin/memini-ai#readme)
+- [Qdrant](https://qdrant.tech/)
+- [FastMCP](https://github.com/jlowin/fastmcp)