tidy-agent

v1.4.5

Published

a day ago

Sovereign Personal Assistant Agent with persistent SQLite Memory, CLI engine, and local Stdio MCP Server

0High
0Medium
0Low

alwkala

tidy tidyfactor agent personal-assistant sqlite mcp memory fts5 sovereign

🤖 Tidy `v1.4.5`

Sovereign Personal Assistant & Office Suite with Persistent SQLite Memory & Local Stdio MCP Server

Give Google Antigravity, Claude Code, Cursor, OpenAI Codex, or Windsurf a dedicated sovereign assistant layer with zero-config persistent memory, subagent delegation, community skills discovery, Universal Skills & Agents Studio, Knowledge Harvester Studio, full B2B CRM, automated itemized invoicing, expense & cashflow telemetry, and instant SQLite FTS5 search.

English • العربية • 📚 Documentation Hub • 📖 User Manual • 🗺️ Roadmap

🌟 Overview & Platform Topology

Tidy is an autonomous personal assistant and sovereign business operations ecosystem built on top of a single local SQLite database as its permanent Single Source of Truth (SSOT). Designed to eliminate cloud lock-in, Tidy unifies cognitive memory, subagents, business pipelines, and micro-apps across your terminal, code editors, and desktop.

📦 Ecosystem Monorepo Packages & Apps

@tidy/core (packages/core): Pure Node 22 + node:sqlite kernel. Houses dynamic schema registration (registerSchema), WAL concurrency tuning, bilingual FTS5 BM25 search, 3-Ring Context model, Community Skills Discovery (skills-loader.js), Universal Multi-Tool Directory Scanner (multi-tool-scanner.js), Skills-LAB 15-Rule Compliance Auditor (skills-validator.js), Boilerplate Scaffolding (boilerplate-generator.js), SQLite Collections (studio.js), Knowledge Harvester (knowledge-harvester.js), Task Brief Synthesizer (brief-generator.js), subagent dispatcher, and micro-apps (Tasks, Snippets, Journal, Vault).
@tidy/office (packages/office): Standalone business operations pack inheriting and superseding PocketOffice. Provides B2B CRM deal pipelines (app_crm_clients), automated itemized invoicing (app_invoices), commercial proposals (app_proposals), expense tracking & cashflow P&L (app_expenses), calendar scheduler, AI Client Dossier synthesizer, and 1-click PocketOffice migration importer.
@tidy/cli (packages/cli): Terminal command interface (tidy binary) with interactive @clack/prompts navigation wizard.
@tidy/mcp (packages/mcp): Stdio JSON-RPC 2.0 Model Context Protocol server exposing 20 intelligent tools and 6 dynamic live resources.
@tidy/skill (packages/skill): Official TidyFactor Skills-LAB Community Skill (Apache-2.0, 15 structural rules).
@tidy/desktop (apps/desktop): Native Windows x64 Desktop Application (Electron + secure typed IPC + global floating HUD summoned via Alt+Space) featuring dedicated visual tabs for Universal Skills & Agents Studio, Knowledge Harvester Studio, CRM, Invoicing, and Cashflow.
@tidy/web (apps/web): Web Management Console running on local HTTP port 3840 with full REST API and Universal Skills & Agents Studio.

Core Capabilities

Pluggable Microkernel Architecture: Pure separation of concerns between core cognitive memory (@tidy/core) and business domains (@tidy/office). Allows custom enterprise deployments (DevOps, Agencies, Developers) without engine bloat.
The 3-Ring Context Architecture:
- Ring 0 (Sovereign Profile): Permanent user preferences and assistant persona (~150 tokens).
- Ring 1 (Domain Firewall): Context switching between dev, marketing, and personal modes without context bleed.
- Ring 2 (Dynamic Working Memory): BM25-ranked FTS5 recall of relevant decisions, rules, and patterns.
Universal Skills & Agents Studio: Native discovery across Claude Code, Cursor, Codex, Windsurf, Copilot, Antigravity/Gemini, Amp, and Aider; built-in monospaced code editor with line numbers, AST sync, and live Markdown preview; non-destructive SQLite SSOT collections & tagging; 15-rule Skills-LAB compliance auditing.
Knowledge Harvester & Agent Brain Extractor: Standalone 2-Pane Master-Detail Studio for scanning, on-demand full document inspection, and atomic ingestion of knowledge items from ~/.gemini/knowledge/**, Antigravity session brain plans, and agent rules with seamless "Open in Studio" bridging.
Sovereign Business Suite: Manage client pipelines, generate tax-calculated itemized invoices, record operational expenses, monitor real-time cashflow telemetry, and generate AI-powered client dossiers.
Pluggable Sub-Agents & Skills Hub: Built-in core roles (planner, coder, researcher, scribe) plus dynamic integration of TidyFactor Skills-LAB community skills (@marketing, @design, @doc, @next, @php, etc.) as sovereign subagents.
Self-Contained Task Brief Generator: Synthesizes autonomous task briefs combining Goal/Mission, 3-Ring Context, Skill Operational Rules, and Verification Gates.
Multi-Surface Access: CLI, Stdio MCP Server, Electron Windows Desktop App (Alt+Space HUD), and Web Dashboard.

🛠️ Quick Start & Usage

💡 For the comprehensive command reference and end-to-end workflows, see the 📖 User Manual.

1. Interactive Terminal Wizard (Recommended)

Launch the modern, interactive @clack/prompts navigation interface:

tidy
# or explicitly:
tidy ui

2. Fast Developer One-Liners & Cognitive Memory

High-speed terminal commands for daily coding and agent collaboration:

# Instant memory search with mathematical decay & stars ranking
tidy q "WAL mode"
tidy q "auth" --bypass   # Bypass domain firewall for global search

# Instant memory capture in 1 second
tidy m "Use WAL mode for high concurrency" --cat decision --imp 5

# Quick task management with autonomous memory feedback loop
tidy task "Implement OAuth2" --priority urgent --domain dev --agent coder
tidy tasks --pending
tidy done tsk_xxx --result "Implemented with JWT verification"  # Auto-archives decision to memory!

# Autonomous Subagent & Skill Runner (3-Ring Context Injection)
tidy run coder "Audit SQLite indexes and foreign keys"
tidy run marketing "Draft product launch post for Twitter"
tidy run doc "Generate API references for MCP endpoints"

# Instant diagnostics, search, and storage hygiene
tidy doc                    # Full SQLite, WAL & knowledge base health check
tidy search "FTS5 BM25"     # Hybrid recall across SQLite DB & disk markdown files
tidy clean                  # Storage audit with dry-run inspection of recordings & caches
tidy firewall "New ad copy" # Instant check against domain bleed

# Quick status & firewall inspection
tidy who
tidy whoami

3. CRM & Client Pipeline

# List active clients
node bin/tidy.js crm list

# Add a new client
node bin/tidy.js crm add --name "Acme Corp" --budget 15000 --status prospect

4. Invoicing & Billing Engine

# List all invoices
node bin/tidy.js invoice list

# Create itemized invoice with 15% tax
node bin/tidy.js invoice create --client cli_xxxx --tax 15 --items '[{"name":"Backend API Migration","qty":1,"unitPrice":4500}]'

# Mark invoice as paid
node bin/tidy.js invoice pay inv_xxxx

5. Expenses & Live Cashflow Telemetry

# Record operational expense
node bin/tidy.js expense add --title "Cloud Server Hosting" --amount 240 --category hosting

# Audit live cashflow statement (Revenue, Expenses, Net Profit, Margin, Receivables)
node bin/tidy.js cashflow

6. AI Client Dossier Synthesizer

# Compile instant executive dossier combining CRM, Invoices, Proposals, and FTS5 Memory
node bin/tidy.js dossier cli_xxxx

7. PocketOffice 1-Click Migration

# Import existing PocketOffice data into Tidy SQLite SSOT
node bin/tidy.js import-pocketoffice --source ./path/to/PocketOffice-Data

8. Save & Recall Memories

# Save an architectural decision
node bin/tidy.js memory save "Project uses Next.js 16 and Supabase with strict tenant isolation"

# Instant BM25 search
node bin/tidy.js memory recall "Next.js"

9. Switch Contexts & Domains

node bin/tidy.js context list
node bin/tidy.js context switch ctx_dev

10. Delegate to Subagents & Synthesize Briefs

node bin/tidy.js agent run coder "Review database schema performance"
node bin/tidy.js brief "Build cashflow analytics dashboard"

🔌 Stdio MCP Server Configuration

Add to your IDE MCP configuration (mcp_config.json):

{
  "mcpServers": {
    "tidy": {
      "command": "node",
      "args": ["packages/mcp/src/server.js"]
    }
  }
}

Registered Tools (29 Tools)

Cognitive & Working Memory: tidy_recall, tidy_memorize, tidy_get_context, tidy_switch_context, tidy_whoami.
Sovereign Brain & Forensic Diagnostics: tidy_doctor, tidy_search, tidy_extract, tidy_transcripts, tidy_hygiene, tidy_firewall, tidy_manifest.
Knowledge Harvester & Brain Extraction: tidy_harvest_scan, tidy_harvest_read, tidy_harvest_import.
Governance & Configuration: tidy_config_get, tidy_config_set, tidy_profile_update, tidy_govern_rules.
Tasks & Autonomous Subagents: tidy_task_add, tidy_task_list, tidy_exec_subagent, tidy_list_skills, tidy_synthesize_brief.
Database Telemetry: tidy_db_stats.
Office Suite (@tidy/office):
- tidy_crm_list: List CRM clients, deal pipelines, and budgets.
- tidy_crm_add: Register a new B2B client.
- tidy_invoice_list: Query invoices by status, client, or due date.
- tidy_invoice_create: Generate itemized invoices with automated tax and discounts.
- tidy_cashflow_summary: Live P&L financial statement.
- tidy_client_dossier: Comprehensive AI client dossier fusing financial ledger and institutional memory.

Dynamic Live Resources (9 Resources)

tidy://profile: Sovereign user profile and operating tone.
tidy://context/current: Active project context and domain firewall constraints.
tidy://tasks/pending: Pending tasks queue.
tidy://brain/doctor: Live system diagnostic health report.
tidy://brain/taxonomy: 4-tier knowledge base taxonomy and index.
tidy://brain/hygiene: Disk storage breakdown and cleanup candidates.
tidy://office/cashflow: Real-time financial cashflow statement.
tidy://config: System configuration provider snapshot.
tidy://govern: Active contextual governance and firewall policies.

Model Context Protocol (MCP) Prompts

task_brief: Synthesize autonomous 3-Ring Task Briefs with operational guidelines.
extract_ki: Atomic Knowledge Item (KI) creator enforcing negative constraints.
firewall_audit: Contextual domain firewall audit guide.
agent / run: Instant autonomous subagent runner with 3-Ring context injection.

Zero-Breakage Legacy Aliases

Seamless backward compatibility for legacy IDE configs with automatic argument normalization (doctor, probe_server_health, recall_memory, search_knowledge_base, extract_knowledge_item, contextual_firewall, get_skill_manifest, whoami).

Remote Web MCP Server (HTTP JSON-RPC 2.0)

Connect IDE agents remotely via POST http://localhost:3840/mcp with complete tool execution, resource subscriptions, and prompts support without local CLI overhead.

🏛️ Architecture & Governance

Tidy adheres strictly to the 15 Structural Rules of TidyFactor Skills:

Dispatcher Discipline: SKILL.md is a clean router (~350 tokens) with explicit anti-triggers.
Contextual Decision Layer (CDL v2.0): Automatic Context Delta Resolution before prompting.
Operational Memory Isolation: Clean separation between pure technical schemas and human documentation.
Pluggable Microkernel: Core engine remains clean, fast, and unpolluted by domain-specific business rules.

📚 Documentation & Ecosystem Guides

The Tidy repository is organized around a single root README.md and a modular Documentation Hub:

| Guide / Specification | Scope & Description | Link | |---|---|:---:| | Documentation Hub | Master index of all project guides, specs, and translations | docs/README.md | | User Manual (العربية) | Comprehensive operating manual for CLI, MCP, HUD & Apps | docs/user_manual.ar.md | | Project Status & SemVer | Active component status & SemVer roadmap (v1.4.3 – v2.0.0) | docs/PROJECT_STATUS.ar.md | | System Architecture | Technical specification of SQLite WAL, FTS5 & Context Rings | ARCHITECTURE.md | | Product Roadmap | Strategic multi-phase product roadmap and release plan | ROADMAP.md | | AI Agent Guidelines | Autonomous coding agent operating contract & invariants | AGENTS.md | | Skill Manifest | TidyFactor Skills-LAB certified skill router | packages/skill/SKILL.md | | Release Changelog | Complete historical SemVer changelog | CHANGELOG.md | | Security Policy | Zero-telemetry guarantee & private vulnerability reporting | SECURITY.md | | Contributing Guide | Development workflows, test suites, and contribution rules | CONTRIBUTING.md |

⚡ Interactive Documentation Portal (VitePress)

Run the local interactive documentation portal with instant search and full RTL/LTR support:

npm run docs:dev    # Start live development server
npm run docs:build  # Compile static production bundle (SSG)

🌐 International Translations (`docs/i18n/`)

العربية (Arabic) • Español • Deutsch • Français • Português • 中文 • فارسی