Skip to content

Home

Jump to bottom
Brian edited this page Aug 12, 2026 · 3 revisions

J.O.S.H.U.A. Operator Guide

Joint Operational Systems for Heuristic User Automation

Welcome to J.O.S.H.U.A.! This manual is divided into two parts: a "Quickstart" for everyday users to get the AI brain up and running, and an "Advanced Operations Manual" detailing the vast enterprise systems (Swarm P2P, Blackbox Vaults, and GitOps integration).

PART 1: QUICKSTART (The Simple Way)

1. Pick a Brain and Stick with It

J.O.S.H.U.A. is totally adaptable—it can use ANY database and ANY embedding model you want. However, you must pick one setup and stick to it forever for that specific project. If you change your model halfway through a project, your agent's brain will scramble because the underlying math will completely change.

We strongly recommend using our RAG 5.21 Architecture:

  • Database: LanceDB (handles semantic "meaning" search and exact-word matching instantly).
  • Embedder: Nomic-Embed-Text (runs offline and free via Ollama).

Step-by-Step Setup:

  1. Download Ollama: Go to ollama.com, download the app, and install it.
  2. Open your terminal and run: ollama pull nomic-embed-text
  3. Ensure the Ollama app is running in the background whenever you use J.O.S.H.U.A.

2. Universal Skill Injection (Required)

Because J.O.S.H.U.A. is CLI-agnostic, skills (like the aim-memory-wiki and aim-handoff) are not hardcoded into the OS. You must inject them into your preferred AI CLI vessel.

We strongly recommend using Symlinks rather than copying the files. By symlinking, any time you run git pull inside the skill library to get updates, all of your agents across every CLI instantly receive the newest skills without you having to re-install anything.

git clone https://github.com/BrianV1981/aim-skill-library.git
cd aim-skill-library

# Example: Install globally for the 'agy' vessel using a symlink
./scripts/install.sh --vessel agy --dest ~/.gemini/antigravity-cli/builtin/skills --mode symlink

Note: The aim-skill-library repository contains detailed installation commands for every CLI harness (including grok, opencode, and local project overrides). Please check its README for your exact CLI setup.

3. Chunking 101 (How Agents Learn)

When saving files for your agent to learn, you can't throw a giant 50-page document into the database at once. The "meaning" gets watered down (semantic dilution).

  • The Golden Rule: Always break your text into pieces of 500 to 1,500 characters.
  • J.O.S.H.U.A. natively handles this chunking math for you when you run the built-in aim index script, but you must remember this rule if you ever build custom tools!

3. The Memory Wiki (Your Project's Diary)

Inside your project is a folder called memory-wiki/.

  • What it IS: A permanent diary for your project where your agent saves rules, architecture decisions, and important discoveries.
  • What it IS NOT: A temporary scratchpad. Do not put junk logs in here.

Any time a new file is added to the wiki, explicitly "feed" it to the database by running:

aim index

PART 2: ADVANCED OPERATIONS MANUAL

1. The Prime Directive: GitOps & Atomic Deployments

AI agents are strictly forbidden from executing raw git commit or git push commands directly on the main branch. All modifications must follow the 3-step atomic pipeline via aim GitOps wrappers.

  1. Report & Track (aim bug): Interfaces with GitHub to issue a formal ticket and returns an Issue ID. Mandatory prerequisite before writing code.
  2. Surgical Isolation (aim fix <Issue_ID>): Automates a git worktree checkout, creating an isolated sandbox directory (workspace/issue-<ID>). Agents must code only here.
  3. Atomic Release (aim promote): Executed from inside the active worktree. Runs test verification, archives main, merges the worktree branch, pushes to GitHub, and destroys the sandbox.

2. Multi-Agent Orchestration (GitHub Projects Kanban)

Agents natively manage project status on GitHub Projects via the aim projects wrapper, coordinating multi-agent swarms without web UI overhead.

  • Read Board: aim projects board
  • Claim Task: aim projects in-progress <issue_id> (Locks assignment).
  • Ship Task: aim projects done <issue_id> (Execute after promotion).
  • Mark Blocked: aim projects blocked <issue_id>

3. Context Management & The Handoff Protocol

Past 30% context window utilization, LLM precision degrades non-linearly (the "Amnesia Problem"). Agents must treat sessions as short sprints.

  1. Document State: The agent invokes the aim-handoff skill to write a structured HANDOFF.md detailing tactical state and epistemic dead ends.
  2. The Tmux Baton Pass: Create a detached tmux session, load HANDOFF.md into the buffer, and submit it to the newly spawned agent vessel so it can resume work with a fresh context window.

4. The Forensic Blackbox Vault (Anti-Tampering)

Designed to solve AI agent tampering (e.g., agents modifying logs to cover errors).

  • Operator-Exclusive Access: A cryptographically encrypted, append-only vault. Agents cannot read or decrypt the vault. They can only seal sessions.
  • Execution: aim <vessel>-blackbox --session-id <uuid> (e.g. aim agy-blackbox --session-id 12345).

5. DataJack Protocol & Sovereign Swarm (P2P Knowledge)

Memory is separated into RAM (mutable LanceDB store) and ROM (immutable Parquet cartridges).

  1. Compile (aim bake <dir> <out.parquet>): Chunks text, embeds via Ollama, and writes an Apache Arrow Parquet cartridge.
  2. Export (aim export <file>): Generates SHA-256 hash and begins seeding via BitTorrent DHT Swarm.
  3. Jack In (aim jack-in <magnet>): Mounts clean cartridges into archive/cartridges/ via Zero-Copy reads (0 token taxation).
  4. Un-Jack (aim unplug <file>): It is critical to "un-jack" (unmount) Parquet cartridges when the specific task is complete. The DataJack system allows an agent to temporarily load vast amounts of specific, "sourced" knowledge (such as the entire documentation for a coding language or framework). When chunked correctly, querying a loaded cartridge via RAG is vastly superior and more accurate than searching the web or relying on the AI's internal base weights. However, leaving dozens of massive cartridges mounted permanently will dilute search results.

6. Eureka Farming (Self-Optimization)

Prevents database pollution caused by storing intermediate trial-and-error logs ("The Thrash").

  • Hindsight Pruning (Manual): Note: This feature is not yet fully automated. Operators must manually rewind successful sessions, squash failed attempts, and extract clean "Problem -> Solution" synthetic records to feed into the wiki.
  • Cartridge Farming (Manual Sharing): Note: Fully automated farming is still in development. However, operators can manually compile and share .parquet files today. The recipient can use them instantly, provided they are using the exact same embedding model and database (e.g., Nomic + LanceDB).

7. Cognitive Architecture & Hybrid Retrieval

  • Hybrid Reranking (RRF): Runs vector similarity and Tantivy keyword search concurrently. Applies a 1.5x score multiplier to fragments matching exact Proper Nouns, curing "Entity Blindness".
  • Sandwich Expansion: Fetches surrounding chunks (N-1 and N+1) to preserve dialogue context boundaries.
  • Graceful Lexical Degradation: If the local Ollama embedding model crashes, LanceDB falls back to 100% Tantivy keyword search without failing.

APPENDIX: Complete CLI Tools Reference

Command Category Command Syntax Description
GitOps aim bug "<desc>" Creates a GitHub issue and returns the Issue ID.
aim fix <issue_id> Spawns isolated Git worktree under workspace/issue-<id>.
aim promote Merges worktree into main, pushes to GitHub, cleans worktree.
aim merge-batch Merges all open non-conflicting fix/* branches into main.
Kanban aim projects board Views active GitHub Projects board status.
aim projects in-progress <id> Claims issue on Kanban board.
aim projects done <id> Marks issue as completed on board.
Knowledge aim search "<query>" Hybrid RAG search (Vector + Tantivy FTS) in LanceDB.
aim index Bootstraps and indexes the local brain.
aim wiki search "<key>" Instant 0ms in-memory lexical search across wiki/.
Telemetry aim <vessel>-blackbox Encrypts raw session transcript into Blackbox Vault.
DataJack P2P aim bake <dir> <out> Compiles directory into compressed Parquet ROM cartridge.
aim export <file> Seeds cartridge to P2P DHT Swarm.
aim jack-in <magnet> Quarantines, scans, and mounts cartridge into archive/.
System Admin aim doctor Diagnoses Node, LanceDB, API keys, and environment health.
aim audit Analyzes history to generate Weekly Sitreps.

CONCLUSION: The Core Philosophy

If you strip away the advanced commands and Swarm protocols, most Operators are here to emulate the memory-wiki / handoff system.

It is vital to understand that this system can be adapted to almost ANY CLI agent workflow or LLM model. If you ask a flagship LLM what makes A.I.M.-style "memory" work, it boils down to two core pillars, paired with an AGENTS.md file for strict directions.

Pillar 1: RAG / Vector Memory

Pick a store + embedder and stick to it. We use LanceDB + Nomic embeddings. The RAG 5.21 architecture is intentionally isolated so you can adapt it without adopting the full J.O.S.H.U.A. stack. You can view the memory engine here: aim-memory

Pillar 2: Agent Skills (The Playbooks)

These are the explicit tools the agent runs to manage its own lifecycle, which are stored in the aim-skill-library:

  • aim-memory-wiki: A Karpathy-style LLM wiki for long-term project lore. It updates every session, lives in the repo, compounds over time, and is natively ingested into LanceDB for search.
  • aim-handoff: A structured handoff document from agent to agent providing immediate tactical context (not a second wiki).
  • aim-flight-recorder: Turns a raw, noisy session log into a clean, readable .md file, which is excellent for human audits and later database ingestion. Code is found here: aim-flight-recorder

The Golden Rule of Thumb

The most important part of this entire system is knowing when to use these skills.

Rule of Thumb: Run the wiki update, generate a handoff, (and extract a flight record if you care about the session), then start a fresh agent BEFORE the context window auto-compacts.

Hallucinations are partly predictable. Once you find the rhythm, this system kills the absolute worst part of agent work: waking a new session and spending 20 minutes re-teaching it and prepping the context just to get back to work.

Clone this wiki locally