AI Contexters

Operator front door for agent session logs.

aicx is store-first:

1. Canonical corpus (~/.aicx/) — extract, deduplicate, chunk, and store agent session logs as steerable markdown with frontmatter metadata. This is ground truth. Built by extractors (claude, codex, all) and store.

2. Retrieval surfaces — filesystem search, steering metadata, MCP tools, and a reusable native embedding library. AICX stays portable; heavy retrieval belongs to Roost/rust-memex.

aicx owns the canonical corpus and the portable local embedding foundation. Roost/rust-memex owns the advanced retrieval/operator plane. The operator-facing oracle contract is in docs/ORACLE_CORPUS.md: raw source logs and the canonical corpus are truth; indexes are derived, rebuildable views that must disclose fallback and Loctree scope safety.

Supported sources:

• Claude Code: ~/.claude/projects/*/*.jsonl
• Codex: ~/.codex/history.jsonl
• Gemini CLI: ~/.gemini/tmp/<hash>/chats/session-*.json
• Gemini Antigravity direct extract: ~/.gemini/antigravity/conversations/<uuid>.pb or ~/.gemini/antigravity/brain/<uuid>/
• loct-context-pack (immutable structural-evidence packs from Loctree prism / polarize): aicx ingest --source loct-context-pack <PACK_DIR> writes into the parallel Context Corpus at ~/.aicx/context-corpus/. See docs/CONTEXT_CORPUS.md.

Context Corpus

Alongside the canonical session-log store, aicx maintains an immutable context corpus at ~/.aicx/context-corpus/ that retains loct-context-pack prism artifacts (structural evidence consumed by vc-polarize gating and doctrine drafting). The corpus is governed by a different contract: append-only, operator-driven (only aicx ingest --source loct-context-pack writes to it), excluded from aicx intents and live-truth retrieval, and materialized into a separate context-corpus.embeddings.ndjson namespace so example evidence never poisons live-session truth.

aicx ingest --source loct-context-pack /path/to/prism-pack
aicx doctor --check-dedup   # cross-namespace duplicate report

Sidecars carry artifact_family=loct-context-pack, schema_version=context_corpus.v1, truth_status.role=Example, and content_sha256. Every ingest batch produces an index.jsonl manifest. Full contract, retention path layout, and immutability filter behavior in docs/CONTEXT_CORPUS.md.

Install

Public install from GitHub Releases:

curl -fsSL https://raw.githubusercontent.com/Loctree/aicx/main/install.sh | AICX_INSTALL_MODE=release AICX_RELEASE_TAG=v0.9.1 bash

The installer downloads the matching release archive, verifies its adjacent .sha256 sidecar, and installs both shipped commands:

aicx --help
aicx-mcp --version

Before it writes binaries, install.sh scans the active install surface with which -a aicx, prints every version it can resolve, and warns if PATH might keep using another channel. After install it compares the installed binary with the PATH-resolved binary. Use bash install.sh --dry-run to preview shadow cleanup, or AICX_INSTALL_FORCE=1 for non-interactive installs you have already checked.

Direct release download with checksum and GPG verification:

version=0.9.0
case "$(uname -s)-$(uname -m)" in
  Darwin-arm64) target=aarch64-apple-darwin; ext=zip ;;
  Linux-x86_64) target=x86_64-linux-gnu; ext=tar.gz ;;
  *) echo "unsupported platform: $(uname -s)-$(uname -m)" >&2; exit 1 ;;
esac

asset="aicx-v${version}-${target}-slim.${ext}"
base="https://github.com/Loctree/aicx/releases/download/v${version}"

curl -fLO "${base}/${asset}"
curl -fLO "${base}/${asset}.sha256"
curl -fLO "${base}/${asset}.asc"

shasum -a 256 -c "${asset}.sha256"
gpg --verify "${asset}.asc" "${asset}"
tar -xzf "${asset}"

From a local checkout:

./install.sh

install.sh installs aicx + aicx-mcp from the current checkout and configures Claude Code, Codex, and Gemini when their MCP settings directories already exist.

From a release bundle:

bash install.sh

Bundle install copies prebuilt aicx + aicx-mcp into ~/.local/bin, removes stale user-local / cargo-installed copies, then refreshes MCP configuration. No Rust toolchain and no local memex compilation are required on the target machine.

From an existing checkout, you can force the same release path:

AICX_INSTALL_MODE=release bash install.sh
AICX_INSTALL_MODE=release AICX_RELEASE_TAG=v0.9.0 bash install.sh

Current release assets are slim bundles for macOS arm64, Linux x64 GNU, and Windows x64 GNU. The .sha256 sidecar is mandatory; detached .asc signatures are published with release archives.

The npm wrapper track exists under distribution/npm/ and ships platform packages for macOS arm64, Linux x64 GNU, and Windows x64 GNU. npm postinstall warns about ~/.local/bin or cargo-bin shadows by default. Set AICX_NPM_REPLACE_LOCAL=1 if npm should remove older or equal local shadows during install.

From an accessible GitHub repo when you want unreleased source:

cargo install --git https://github.com/Loctree/aicx --locked aicx

Already installed the binaries?

./install.sh --skip-install

Manual fallback:

cargo install --path . --locked --bin aicx --bin aicx-mcp
./install.sh --skip-install

install.sh prefers a colocated release bundle first, then a local checkout, and otherwise falls back to the published install path.

See docs/install-paths.md for the full channel map and shadow cleanup model.

Maintainer-local signed bundle path on macOS:

make release-bundle KEYS=~/.keys
make release-bundle KEYS=~/.keys NOTARY_PROFILE=vc-notary

Store a local Apple notary profile from operator-owned credentials:

set -a
source "$HOME/.keys/.notary.env"
set +a

xcrun notarytool store-credentials "${NOTARY_PROFILE:-vc-notary}" \
  --apple-id "$NOTARY_APPLE_ID" \
  --team-id "$NOTARY_TEAM_ID" \
  --password "$NOTARY_PASSWORD"

That release path cleans target/<triple> after the bundle is safely written so the self-hosted box does not keep hauling old release artifacts. Use CLEAN=0 when you explicitly want to keep the local build outputs.

Native embedder profiles:

• base — F2LLM-v2 0.6B Q4_K_M GGUF, 1024 dims, about 397 MB
• dev — F2LLM-v2 1.7B Q4_K_M GGUF, 2048 dims, about 1.1 GB
• premium — F2LLM-v2 1.7B Q6_K GGUF, 2048 dims, about 1.4 GB
• Picker during install: bash install.sh --pick-embedder

Config truth:

• AICX native embedder preferences live in ~/.aicx/embedder.toml or AICX_EMBEDDER_CONFIG.
• The picker writes backend = "gguf", profile, repo, and exact filename; model hydration is explicit.
• Roost/rust-memex retrieval config remains separate, usually ~/.rmcp-servers/rust-memex/config.toml or RUST_MEMEX_CONFIG.
• Current public release bundles stay slim; they do not auto-bundle model weights.

Quickstart

aicx wizard opens the interactive entrypoint for browsing the corpus, running doctor, watching store progress, and viewing the intents timeline. Press ? inside the wizard for the keymap.

Library API

aicx is also a Rust library. The supported facade is aicx::Aicx; callers do not need to import command-line internals from main.rs.

use aicx::prelude::*;

let client = Aicx::from_env() ?;
let status = client.index_status(None) ?;
let chunks = client.list_chunks() ?;

For embedding AICX into another service, construct a handle with an explicit store root and write timeline entries directly:

use aicx::prelude::*;

let client = Aicx::with_store_root("/tmp/aicx");
let summary = client.store_entries( & entries, & StoreOptions::default ()) ?;

Layer 1 — build the canonical corpus

Extract the last 4 hours into ~/.aicx/. Extractors are quiet on stdout by default (--emit none).

aicx all -H 4                      # daily driver: watermark-tracked, skips already-processed entries
aicx all -H 0                      # all time: no lookback cutoff
aicx store -p MyProject -H 720     # store-first: watermark-tracked refresh into the canonical corpus
aicx store -p MyProject -H 720 --full-rescan  # explicit backfill / recovery pass

-p/--project on extractors and store narrows source session discovery before repo segmentation. One run can still resolve into multiple canonical repo buckets or non-repository-contexts; --emit json makes that explicit through requested_source_filters and resolved_store_buckets.

See what landed:

aicx refs -H 4
aicx refs -H 4 --emit paths
aicx read store/VetCoders/aicx/2026_0502/reports/codex/2026_0502_codex_sess_001.md

Surface contract:

• aicx refs is the active CLI inventory command for canonical chunks.
• aicx read is the direct re-entry command for paths returned by refs, search, dashboard chunk APIs, or MCP retrieval tools.
• There is currently no aicx rank CLI subcommand; ranking stays on the MCP surface as aicx_rank.
• aicx init is retired; framework bootstrap now lives in /vc-init.

Native local embeddings

AICX ships the reusable aicx-embeddings library behind the native-embedder feature. The installed bundle does not carry model weights; the picker can write config and optionally hydrate exactly one GGUF file:

bash install.sh --pick-embedder
hf download mradermacher/F2LLM-v2-0.6B-GGUF F2LLM-v2-0.6B.Q4_K_M.gguf

The config file is plain TOML:

[native_embedder]
backend = "gguf"
profile = "base"
repo = "mradermacher/F2LLM-v2-0.6B-GGUF"
filename = "F2LLM-v2-0.6B.Q4_K_M.gguf"
prefer_embedded = false
max_length = 512

Pipe one JSON payload (handy for automation):

aicx all -H 4 --emit json | jq '.store_paths'
aicx all -H 4 --emit json | jq '.resolved_store_buckets'

What Gets Written Where

Layer 1 — canonical store (extractors, store)

• ~/.aicx/store/<organization>/<repository>/<YYYY_MMDD>/<kind>/<agent>/<YYYY_MMDD>_<agent>_<session-id>_<chunk>.md
• ~/.aicx/non-repository-contexts/<YYYY_MMDD>/<kind>/<agent>/<YYYY_MMDD>_<agent>_<session-id>_<chunk>.md
• ~/.aicx/index.json

Native embedder config

• ~/.aicx/embedder.toml — local GGUF backend/profile/repo/filename/path preference
• HuggingFace cache snapshots under ~/.cache/huggingface/hub/

Framework-owned repo-local context artifacts (not written by the aicx CLI itself):

• .ai-context/share/artifacts/SUMMARY.md
• .ai-context/share/artifacts/TIMELINE.md
• .ai-context/share/artifacts/TRIAGE.md

Store ignore contract:

• Optional ~/.aicx/.aicxignore excludes matching canonical chunk paths from steer indexing and downstream retrieval materialization.
• Patterns are matched relative to ~/.aicx/ using glob syntax, for example:

store/VetCoders/ai-contexters/**/reports/**
!store/VetCoders/ai-contexters/**/reports/2026_0406_codex_important_001.md

Common Workflows

Daily “what changed?” with incremental refresh plus compact summary:

aicx all -H 24 --emit none
aicx refs -H 24

Full-window backfill (ignore the stored watermark explicitly):

aicx all -H 168 --full-rescan

User-only mode (smaller output; excludes assistant + reasoning):

aicx claude -p CodeScribe -H 48 --user-only

Steering retrieval (filter chunks by frontmatter metadata):

aicx steer --run-id mrbl-001
aicx steer --project ai-contexters --kind reports --date 2026-03-28
aicx steer --agent claude --date 2026-03-20..2026-03-28

Direct chunk re-entry:

aicx search "doctor sidecars" --json
aicx read /Users/polyversai/.aicx/store/VetCoders/aicx/2026_0502/reports/codex/2026_0502_codex_sess_001.md --max-chars 4000

aicx search --json, aicx steer --json, aicx intents --emit json, and the matching MCP tools include oracle_status. Fuzzy search is visibly marked as a filesystem fallback, not semantic oracle readiness.

Native embedder hydration — picking the local model without bloating the bundle:

bash install.sh --pick-embedder
cat ~/.aicx/embedder.toml

Heavy retrieval lives outside this CLI surface:

• Use Roost/rust-memex for advanced retrieval pipelines, provider routing, and operator-scale indexing.
• Keep Roost/rust-memex settings in its own config plane (RUST_MEMEX_CONFIG, usually ~/.rmcp-servers/rust-memex/config.toml).
• Do not put the heavy retrieval provider config into ~/.aicx/embedder.toml; that file governs only AICX local embeddings.

Example Roost/rust-memex provider config:

[embeddings]
required_dimension = 2560

[[embeddings.providers]]
name = "mlx-local"
base_url = "http://127.0.0.1:1234"
model = "qwen3-embedding-4b"
priority = 1

Single-session Gemini Antigravity extract (conversation artifacts first, explicit step-output fallback):

aicx extract --format gemini-antigravity \
  ~/.gemini/antigravity/conversations/<uuid>.pb \
  -o /tmp/antigravity-report.md

Review Vibecrafted workflow and marbles artifacts as a standalone dossier:

aicx reports \
  --repo ai-contexters \
  --workflow marbles \
  --date-from 2026-04-10 \
  --date-to 2026-04-12 \
  -o ~/.aicx/aicx-reports.html \
  --bundle-output ~/.aicx/aicx-reports.bundle.json

The generated HTML embeds the selected slice directly and can also import/export compatible JSON bundles client-side, so you can merge multiple workflow slices without standing up a server.

Local browsing now shares one surface:

# Static HTML artifact (default output: ~/.aicx/aicx-dashboard.html)
aicx dashboard --generate-html -p ai-contexters -H 24

# Live local server
aicx dashboard --serve -p ai-contexters -H 24

# Remote / Tailscale server with explicit CORS policy
aicx dashboard --serve --host 0.0.0.0 --allow-cors-origins tailscale --bg

The tailscale CORS preset accepts both tailnet IP origins and MagicDNS browser origins (*.ts.net).

Intent Taxonomy

The intent engine classifies stored chunks into 9 semantic types with typed link relations:

Type	What it captures	Initial state
intent	User-expressed goal or proposal	proposed
why	Motivation behind a decision	active
argue	Multi-voice disagreement or trade-off	active
decision	Crystallized choice from discussion	active
assumption	Hypothesis treated as true until verified	proposed
outcome	Broad result of an action	done
result	Concrete measurable data point	done
question	Open knowledge gap	proposed
insight	Reframe backed by research evidence	active

Link types: derived_from, supersedes, verifies, contradicts, supports, results_in, answers, links_to.

State transitions: Proposed → Active → Done/Superseded/Contradicted. Session-level post-processing detects unresolved intents (no outcome after 7 days), supersedes chains (newer entry on same topic), contradicted assumptions (result + failure signal), and insight sourcing (DerivedFrom links to research chunks).

aicx migrate
aicx migrate-intent-schema
aicx migrate-intent-schema --project MyProject --dry-run

Docs

• docs/ARCHITECTURE.md (module map + data flows)
• docs/COMMANDS.md (exact CLI reference + examples)
• docs/STORE_LAYOUT.md (store + framework-owned .ai-context/ layouts)
• docs/REDACTION.md (secret redaction, regex engine notes)
• docs/SOURCE_PROTECTION.md (opt-in local source protection and sharing policy)
• docs/DISTILLATION.md (chunking/distillation model + tuning ideas)
• docs/RELEASES.md (release/distribution workflow + maintainer checklist)

Notes

• Secrets are redacted by default on corpus-building commands (claude, codex, all, extract, store). Disable only if you know what you’re doing: --no-redact-secrets.
• Framework integration expects aicx or aicx-mcp in PATH.
• Native embedding models are never downloaded silently by package install or MCP startup.

---

Vibecrafted with AI Agents by VetCoders (c)2026 VetCoders