AI-Continuum: Agent Memory Workspace

AI-Continuum was formerly AI-OS.

AI-Continuum is a secure, local-first memory workspace for AI agents. It preserves durable preferences, rules, skills, templates, project context, resource references, and hard-earned operating knowledge in portable Git-backed files.

       Own the vault. Rent the intelligence. Swap the agents.

The public release stays generic. Personal profiles, real projects, notes, captures, and handoffs belong on a personal branch or fork, never committed directly to release main.

---

1. System Architecture

AI-Continuum organizes data across cognitive, systems, and durability tiers, bridging local SQLite with portable git-backed vault curation.

graph TD
    subgraph "Human / Client Boundary (Cognitive Tier)"
        H["Raw Human Input / Voice Dictation"] --> AIC["AI Client / Claude / Codex"]
        AIC -->|"5-Point Response Contract"| H
    end

    subgraph "Operational Server Boundary (Systems Tier)"
        AIC -- "memory.record_raw_capture" --> SQLite[("Local SQLite WAL hot.db")]
        AIC -- "memory.create_draft" --> SQLite
        AIC -- "memory.approve_draft" --> SQLite
        
        SQLite <-->|Sync Client / bearer-token sync| Edge["Cloudflare Workers Sync Bridge"]
        Edge <--> D1[("Cloudflare D1 Ledger")]
        
        EM["Event Materializer"]
        SQLite --> EM
        EM -->|Materialize Approved Drafts| Inbox["Curation Inbox coauthor-*.md"]
        Inbox -->|Curator review & git commit| Git[("Local Git Repository")]
    end

Loading

---

2. Core Capabilities

📱 SQLite WAL & Cloud Bridge Sync (Option A.5 Sync)

• SQLite WAL Hot Tier: High-frequency writes (chat turns, notes, captures) write immediately to local SQLite. WAL mode ensures lock-free concurrency and merges SQLite rows with legacy .jsonl files.
• Cloudflare Event Bridge: A bearer token-secured Cloudflare Workers + D1 database providing batch /events/push and /events/pull edge synchronization with per-device cursor offsets.
• Obsidian Mobile Capture Integration: Enables phone captures to post directly to the Workers bridge, falling back gracefully to local Markdown file generation if offline.

🤖 AI-Continuum Human Thought Co-Author Engine

Enables humans to write/dictate notes badly, preserves the original raw transcripts permanently in event logs, structures beautiful drafts, and writes them to the curation inbox upon approval.

• The 5-Point Response Contract: Format every co-author interaction using this standard:
  1. What I think you mean: Inferred core intent.
  2. Clean draft: Polished, schema-validated Markdown block.
  3. Missing details: Questions about missing triggers, gotchas, or anchors.
  4. Suggested artifact type: Capsule, handoff, skill, or capture.
  5. Save destination: Proposed relative vault path.
• Inbox Materialization: Approved drafts automatically compile into review candidates: vault/memory/inbox/coauthor-*.md, embedding the raw transcript excerpt and keeping humans in the loop before durability.

🔑 Zero-Knowledge Secret-Locator Sync

• Metadata-Only References: Real passwords and API keys are never committed or synced. Secret locators only hold generic reference descriptors.
• Zero-Knowledge Presence Verification: Local presence checks for 1Password (op) or Bitwarden (bw) CLI tools query item/vault metadata only, completely discarding output streams. The secret value is never decrypted or materialized inside child processes during checks.
• Governed In-Memory Materialization: A default-denied secret.materialize entry can resolve a value into process memory only through an approved backend — a managed-vault session the human has unlocked (1Password / Bitwarden), or Bitwarden Secrets Manager via a scoped, read-only BWS_ACCESS_TOKEN (bitwarden-sm). Every attempt writes a redacted audit report and the value is never serialized; environment / local-env-file backends and 1Password service-account mode are refused. See stage-26 and stage-27.

🛡️ Curation Governance PR Flow & 24h Stomp Protection

• GitHub Pull Request Flow: Automated cron workflows (curate-vault.yml) checkout unique daily branches and automatically open GitHub Pull Requests (gh pr create) instead of silently pushing to main (fully complying with the vault write protocol).
• 24-hour Stomp Protection: Before applying any curation promotions, the curator checks git log --since=24.hours over the target file. If a human edited it in the last 24 hours, the curator skips the mutation and flags a 24h_stomp_detected item in the curation report for review.

---

3. Directory Structure

vault/       durable agent memory, knowledge capsules, project packs, and reports
platform/    operational applications (MCP server, Python curator-runner, schemas, CI)
ai-coding/   authoritative governance playbooks and rules for agents working on this repo
docs/        portable specifications, system context, user quickstarts, and runbooks
scripts/     cross-platform PowerShell and Bash operational wrappers

---

4. Getting Started

For a comprehensive step-by-step walkthrough on profile personalization, co-authoring workflows, secret locators, and Cloud sync deployment, read the Developer Getting Started Guide.

New PC with a separate personal vault

The personal GitHub repo is the data/vault repo. The ai-os command comes from an AI-Continuum source checkout or installed package, then points at the personal repo:

git clone <ai-os-source-repo-url> ai-os
git clone <your-personal-vault-repo-url> my-ai-os
cd ai-os

# Install source checkout dependencies once before using npm run ai-os.
.\scripts\ai-os-first-run.ps1 -Install -NoChecks
# macOS/Linux:
# ./scripts/ai-os-first-run.sh --install --no-checks

npm run ai-os -- init --repo ..\my-ai-os --project first-project
npm run ai-os -- doctor --repo ..\my-ai-os
npm run ai-os -- launch --repo ..\my-ai-os --open
npm run ai-os -- index --repo ..\my-ai-os
npm run ai-os -- recall --repo ..\my-ai-os --query "what should AI-Continuum remember?"

After AI-Continuum is published and installed as a package, use the same commands without npm run:

ai-os init --repo D:\path\my-ai-os --project first-project
ai-os doctor --repo D:\path\my-ai-os
ai-os launch --repo D:\path\my-ai-os --open

Windows (PowerShell)

# 1. Clone the repository
git clone https://github.com/samartomar/ai-continuum.git
cd ai-os

# 2. Run the doctor checklist and install dependencies
.\scripts\ai-os-first-run.ps1 -Install

# 3. Branch into a personal profile space
.\scripts\ai-os-onboard.ps1 -Name "Your Name"

# 4. Create your first project pack space
.\scripts\ai-os-new-project.ps1 -Name "My Project" -Purpose "A clean workspace goal."

# 5. Launch the Operator Dashboard
.\scripts\ai-os-launch.ps1 -Open

macOS / Linux (Bash)

# 1. Clone the repository
git clone https://github.com/samartomar/ai-continuum.git
cd ai-os

# 2. Run the doctor checklist and install dependencies
./scripts/ai-os-first-run.sh --install

# 3. Branch into a personal profile space
./scripts/ai-os-onboard.sh --name "Your Name"

# 4. Create your first project pack space
./scripts/ai-os-new-project.sh --name "My Project" --purpose "A clean workspace goal."

# 5. Launch the Operator Dashboard
./scripts/ai-os-launch.sh --open

The launch command refreshes status, compiles the local human-facing operator dashboard, and opens .var/dashboard/index.html in your default browser.

---

5. Summary of Operational CLI Pipelines

• Co-Author Pipeline:

  # Record raw dictated thought
  npm run ai-os:coauthor -- --title "Raw Dictation" --file notes.txt
  
  # Approve and materialize draft to inbox candidate
  npm run ai-os:coauthor -- --title "Raw Dictation" --file notes.txt --approve

• Sync Edge Events:

  npm run ai-os:sync

• Secret Locator Contract Reports:

  npm run secret-locator:contract -- --locator "graphify-api-key"

• Materialize Inbox Candidates:

  npm run ai-os:materialize

• Trigger Graph Indexing:

  npm run graph:index

• Verify System Integrity:

  # Quick check
  ./scripts/ai-os-verify.sh
  
  # Full checklist check
  ./scripts/ai-os-verify.sh --full

---

6. Obsidian & Mobile Integration

Obsidian Vault Setup

Open vault/ directly as an Obsidian Vault on your desktop to get a beautiful visual interface for managing your profile, projects, handoffs, and curation inbox.

Mobile Capture Plugin Setup

Enable background mobile captures without requiring an Obsidian Sync subscription:

# Install the plugin locally to your vault
./scripts/ai-os-obsidian-plugin-install.sh

Open Obsidian, enable the AI-Continuum Mobile Capture community plugin, and configure the local repository path and auto-sync triggers directly inside the settings tab!

Offline captures are written as plain Markdown under vault/captures/mobile-inbox/. They are ingested into the canonical review surface (vault/memory/inbox/) the next time captures are materialized — which happens automatically whenever you open the review queue (ai-os memory-review) — so phone notes show up for review alongside everything else.

---

7. Verification & Tests

Automated Test Suites

AI-Continuum is covered by comprehensive, rigorous, and automated unit/integration tests running locally and on CI.

• Node.js/Vitest Suite:

  cd platform/apps/mcp-server
  npm test

• Python Curator Suite:

  cd platform/apps/curator-runner
  uv run python -m unittest discover -s tests

• Vault Schema Compliance Check:

  cd platform/apps/mcp-server
  npm run validate-vault

---

8. License

AI-Continuum is released under the MIT License.