mycontextprotocol

Self-hosted personal memory and context management system

Status: 🚧 Active Development - Phase 1.5 (Dev Toolchain)

A cloud-agnostic, Kubernetes-based system for capturing, organizing, and querying personal context using hybrid AI (vector search + knowledge graphs).

Overview

mycontextprotocol combines:

• PostgreSQL + pgvector for vector embeddings and structured storage
• Mem0 (library) for AI-powered fact extraction and entity resolution
• LlamaIndex for semantic search and property graphs
• Dragonfly for queue and cache (Redis-compatible)
• KEDA for event-driven autoscaling
• K3s for lightweight orchestration

Designed for single-user deployment on Oracle Cloud Free Tier, but runs anywhere Kubernetes does.

Quick Links

• Architecture - Full system design and phases
• Development Workflow - Agent workflow and patterns
• Code Style - Conventions and standards
• Agent Instructions - GSD planning docs and workflow

Quick Start

Prerequisites

• Nix with flakes enabled
• Docker daemon running
• Python 3.13 (managed by Nix)

Get Started

# 1. Enter dev environment
nix develop

# 2. Install Python dependencies
uv sync

# 3. Run quality checks
task check          # Format + lint + typecheck

# 4. Check available work
cat .planning/STATE.md

# 5. Database operations (Phase 1.5+)
task db:autogenerate -- "migration message"  # Generate from models
task db:upgrade                              # Apply migrations

# 6. Start local cluster (Phase 2+)
k3d cluster create --config k3d/local.yaml
helmfile sync

Development Commands

Command	Purpose
task check	Run all quality checks (format + lint + typecheck)
task format	Auto-format code with ruff
task lint	Check code quality with ruff
task typecheck	Verify types with basedpyright
task db:upgrade	Apply database migrations
cat .planning/STATE.md	Review backlog and priorities
cat .planning/PLAN.md	Review active work plan

Project Structure

mycontextprotocol/
├── .agentinstructions/     # Architecture, development workflow
├── src/
│   └── mycontextprotocol/  # Python application code
│       └── models.py       # SQLAlchemy models (schema source of truth)
├── alembic/                # Database migrations (autogenerated)
├── infra/
│   ├── k8s/               # Helmfile, Kubernetes manifests
│   └── charts/            # Helm charts
├── k3d/                   # K3d cluster configs
├── scripts/               # Helper scripts
├── pyproject.toml         # Python project config + dependencies
├── Taskfile.yml           # Development tasks
├── lefthook.yml           # Git hooks config
└── flake.nix              # Nix dev environment

Development Stack

This project uses:

• Nix flakes - Reproducible dev environments
• uv - Fast Python package manager with deterministic locks
• ruff - Fast linter + formatter (replaces black/isort/flake8)
• basedpyright - Type checker (Pydantic v2 native)
• lefthook - Git hooks (respects Nix PATH)
• Taskfile - Task automation (YAML-based, simpler than Make)
• Alembic - Database migrations (from SQLAlchemy models)
• Python 3.13 - Latest stable Python

See .agentinstructions/DEVELOPMENT.md for complete workflow.

Architecture Highlights

• Subjective/Objective Split: Mem0 (user preferences) vs LlamaIndex (facts)
• State vs Tools Pattern: Context auto-injected (middleware) vs on-demand retrieval (LLM-decided)
• KEDA + Containers: Event-driven autoscaling without FaaS lock-in
• CloudNativePG: Declarative Postgres with pgvector for embeddings
• Dragonfly: Redis-compatible queue + cache (low memory, ARM64 optimized)
• Cloud-agnostic: Runs on K3s anywhere (Oracle Cloud ARM, local k3d)

See .agentinstructions/ARCHITECTURE.md for complete details.

Contributing

This is a personal project, but contributions welcome. Follow:

1. Read .agentinstructions/CODE_STYLE.md
2. Review .planning/STATE.md for backlog
3. Track active work in .planning/PLAN.md
4. Submit PR

License

(To be determined)