AI Contexters

Operator front door for agent session logs.

aicx is store-first:

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.
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>/

Install

Public install from GitHub Releases:

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

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

aicx --help
aicx-mcp --version

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.6.6 bash install.sh

Current release assets are slim unsigned .tar.gz bundles for macOS arm64, Linux x64 GNU, and Linux arm64 GNU. The .sha256 sidecar is mandatory.

The npm wrapper track exists under distribution/npm/, but it is not the supported v0.6.5 install path until its platform packages are aligned with the current GitHub Release asset shape.

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.

Maintainer-local signed bundle path on macOS:

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

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 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.

aicx 0.6.6