AIMFP

AIMFP: AI Modular Functional Procedural Programming

A language-agnostic programming paradigm designed for AI-generated and AI-maintained codebases

---

Table of Contents

• What is AIMFP?
• Core Principles
• Architecture Overview
• Database Architecture
• How It Works
• Getting Started
• Platform Support
• Directives System
• Project Lifecycle
• Example Workflow
• Documentation
• Development
• Design Philosophy
• Features
• Usage Examples
• Privacy Policy
• Support
• License

---

What is AIMFP?

AIMFP (AI Modular Functional Procedural) is a programming paradigm that combines:

• Pure functional programming principles (referential transparency, immutability, composability)
• Procedural execution patterns (explicit sequencing, no hidden state)
• Database-driven project management (persistent state, instant context retrieval)
• Directive-based AI guidance (deterministic workflows, automated compliance)

Two Ways to Use AIMFP

Use Case 1: Regular Software Development

• Build applications (web apps, libraries, CLI tools, etc.)
• AIMFP enforces FP compliance and manages your project
• You write code, AI assists with FP standards and project tracking
• Example: Building a web server, calculator library, data processor

Use Case 2: Custom Directive Automation

• Define automation rules (home automation, cloud management, workflows)
• AIMFP generates and manages the automation codebase for you
• You write directive definitions (YAML/JSON/TXT), AI generates the implementation
• The project's code IS the automation code generated from your directives
• Example: Smart home control system, AWS infrastructure manager, workflow automator

Key Principle: One AIMFP instance per project directory. You would NOT mix a web app with home automation directives. Run separate instances for separate purposes.

Why AIMFP?

Traditional programming paradigms were designed for humans. AIMFP is optimized for AI-human collaboration:

---

Core Principles

1. Functional-Procedural Hybrid

# ✅ AIMFP-Compliant

def calculate_total(items: List[Item]) -> float: """Pure function: deterministic, no side effects""" return reduce(lambda acc, item: acc + item.price, items, 0.0)

❌ Not AIMFP-Compliant

class Calculator: def init(self): self.total = 0 # Hidden state

def add_item(self, item): self.total += item.price # Mutation

2. Database-Indexed Logic

Every function, file, and dependency is tracked in SQLite. AI accesses this data through helper tools — not raw SQL:

AI calls: get_functions_by_file(file_id)

→ Returns: all functions in that file with name, purpose, parameters, returns

No source code reparsing required. Instant context retrieval across sessions.

3. AI-Readable Code

• Flat structure: No deep inheritance hierarchies
• Explicit dependencies: All parameters passed explicitly
• Pure functions: Same inputs → same outputs
• Metadata annotations: Machine-readable function headers

4. Finite Completion Paths

Project: MatrixCalculator

├── Completion Path (3 stages) │ ├── 1. Setup (completed) │ ├── 2. Core Development (in progress) │ │ ├── Milestone: Matrix Operations │ │ │ ├── Task: Implement multiply │ │ │ ├── Task: Implement transpose │ │ │ └── Task: Add validation │ │ └── Milestone: Vector Operations │ └── 3. Finalization (pending)

5. Language-Agnostic

AIMFP works with Python, JavaScript, TypeScript, Rust, Go, and more. FP directives adapt to language-specific syntax while maintaining universal standards.

---

Architecture Overview

┌─────────────────────────────────────────────────────┐

│ AI Assistant (Claude, GPT-4, etc.) │ │ - Receives natural language commands │ │ - Follows directives (FP baseline + project mgmt) │ │ - Calls MCP tools to read/write databases │ │ - Generates FP-compliant code │ └────────────────────┬────────────────────────────────┘ │ MCP Protocol (JSON-RPC over stdio) ┌────────────────────▼────────────────────────────────┐ │ MCP Server │ │ - Exposes helper tools via JSON-RPC │ │ - Manages four-database connections │ │ - Provides CRUD helpers for all databases │ │ - No business logic — AI makes all decisions │ └───┬────────────────────┬─────────────────────────┬──┘ │ │ │ ┌───▼──────────────┐ ┌───▼────────────────┐ ┌─────▼─────────────────┐ ┌──────▼────────────────┐ │ aimfp_core.db │ │ project.db │ │ user_preferences.db │ │ user_directives.db │ │ (Global, │ │ (Per-Project, │ │ (Per-Project, │ │ (Per-Project, │ │ Read-Only) │ │ Mutable) │ │ Mutable) │ │ Optional) │ │ │ │ │ │ │ │ │ │ - FP directives │ │ - Project metadata │ │ - Directive prefs │ │ - User directives │ │ - Project mgmt │ │ - Files & funcs │ │ - User settings │ │ - Execution stats │ │ - User prefs │ │ - Task hierarchy │ │ - AI learning log │ │ - Dependencies │ │ - User systems │ │ - Themes & flows │ │ - Tracking features │ │ - Generated code refs │ │ - Helper defs │ │ - Completion path │ │ (All opt-in) │ │ - Source file tracking│ │ - Directive flow │ │ - Runtime notes │ │ │ │ (Logs in files) │ └──────────────────┘ └────────────────────┘ └───────────────────────┘ └───────────────────────┘

Use Case 2 adds a second path that never touches the MCP server. Your automation has to run when no AI session is open, so it imports AIMFP as a plain library instead:

┌──────────────────────────────┐        ┌──────────────────────────────┐

│ cron / systemd / your daemon │ │ AI Assistant (a session) │ │ runs forever; AIMFP does not │ │ present only when you are │ └───────────────┬──────────────┘ └───────────────┬──────────────┘ │ starts │ MCP ┌───────────────▼──────────────┐ ┌───────────────▼──────────────┐ │ runner.py (YOUR project) │ │ MCP Server │ │ generated by AIMFP, owned │ │ │ │ and editable by you │ │ check_directive_health │ │ │ │ get_directive_execution_stats│ │ import aimfp.hooks ◄────────┼── a │ get_recent_directive_errors │ │ get_due_directives(...) │ library │ │ run_directive(...) │ call, └───────────────┬──────────────┘ └───────────────┬──────────────┘ not RPC │ reads │ writes │ └────────────► user_directives.db ◄────┘

• .aimfp-project/logs/

The runner writes; the AI reads it back later. AIMFP itself is inert in between — it has no timer and starts nothing.

---

Database Architecture

aimfp_core.db (Global, Read-Only)

Location: Within MCP server installation directory (user-defined location, configured in AI client)

Purpose: Immutable knowledge base containing all AIMFP standards, directives, and helper definitions.

Key Tables:

• directives: All FP, project, and user preference directives (workflows, keywords, thresholds)
• helper_functions: Database, file, Git, and FP utilities organized across multiple registry files
• directive_helpers: Many-to-many junction table mapping directives to their helper functions with execution metadata
• categories: Directive groupings (purity, immutability, task management, etc.)
• directive_flow: Status-driven directive navigation and routing

Helper-Directive Relationship (New in v1.4):

• One directive can use many helpers, one helper can serve many directives
• Junction table stores: execution context, sequence order, parameter mappings
• Enables flexible helper reuse and clear execution flow
• Defined in directive_helpers junction table in aimfp_core.db

Helper Classification:

• Tool: All helpers are exposed as MCP tools (AI calls directly via MCP)
• Sub-helper (is_sub_helper = TRUE): Internal utility called by other helpers only (not exposed to AI)

Helper Registry (Development Staging):

• Helper definitions maintained in dev/helpers-json/*.json during development
• Developers modify JSON files, then import to database when complete
• Each helper includes used_by_directives field for relationship mapping
• Database import script populates aimfp_core.db from JSON files before release
• Production: Users query aimfp_core.db (pre-populated), NOT JSON files
• JSON files are dev-only staging area, never shipped with package

Read-Only Philosophy: This database is version-controlled and immutable once deployed. AI reads from it but never modifies it.

project.db (Per-Project, Mutable)

Location: /.aimfp-project/project.db

Purpose: Persistent state for a single AIMFP project. Tracks code structure, tasks, and runtime notes.

Key Tables:

• project: High-level metadata (name, purpose, goals, status, user_directives_status, last_known_git_hash)
• files, functions, interactions: Code structure tracking
• themes, flows: Organizational groupings
• completion_path, milestones, tasks, subtasks, sidequests, items: Hierarchical roadmap
• task_files: Files worked on for each task/subtask/sidequest — linked automatically while the item is in progress
• modules, module_files, file_flows: Reusable code boundaries and file-to-flow assignments
• notes: Runtime logging with optional directive context (source, severity, directive_name)
• types: Algebraic data types (ADTs)
• infrastructure: Project setup (language, packages, testing)
• work_branches: Git collaboration metadata (user, purpose, merge strategy)
• merge_history: FP-powered merge conflict resolution audit trail

User Directives Integration: The project.user_directives_status field tracks whether user directives are initialized (NULL/in_progress/active/disabled), allowing aimfp_run and aimfp_status directives to include user directive context when active.

Enhanced Notes: The notes table now includes source (user/ai/directive), directive_name (optional context), and severity (info/warning/error) for better traceability.

user_preferences.db (Per-Project, Mutable)

Location: /.aimfp-project/user_preferences.db

Purpose: User-specific AI behavior customizations and opt-in tracking features.

**Ke