auxly-memory-cli

One memory. Every AI agent. On your machine.

Auxly is a local-first, file-based memory layer that every AI agent you use — Claude, Codex, Gemini, Copilot, Cursor, Antigravity, and any CLI agent — reads from and writes to as a single shared source of truth.

No cloud. No database. No vendor lock-in. Just Markdown files you own, with an audit trail you can read and a review queue you control.

One local dashboard for every agent you use — connected brands, memory by category, recent writes, and live remote connections.

🆕 What's New in Version 1.3.0

A major security and usability milestone — vault encryption at rest, one-command SSH pairing, real-time recall playgrounds, fact decay & review, and contradiction sweeps.

• 🔒 Vault encryption at rest. Run auxly encrypt init to secure memory files via age X25519 encryption, storing keys in the macOS Keychain or 0600 file fallback outside the vault. It operates fail-closed, prunes index plaintext, and allows safe git syncing of ciphertext.

• 🔑 One-command pairing. Mints secure, single-use invitation tokens via auxly host invite (TUI [i]), which consumer machines join atomically using auxly join <token> over safe host-key-pinned SSH connections.

• 🎮 Recall playground. Hit ? in the TUI Memory tab to test queries against the real recall pipeline with live score bars, relevance floor indicators, and provider lenses showing exactly what connected ACLs permit.

• ⏳ Fact decay & review. Keep your vault clean. auxly review and TUI Review (-) identify stale, recall-silent facts using a first-seen ledger, allowing you to archive them to .archive/ (never deleted) or restamp them.

• 🧹 Contradiction sweep. auxly organize --contradictions spots cross-file similar facts using embeddings, resolves duplicates/clashes via a single LLM call, and queues them for pending review with dated traces.

• 📈 Trust auto-tuning. Suggests promotions (to auto) or demotions (to read_only) for agents automatically as approval evidence accumulates.

• 🗂️ Memory browser. Browse and edit your full memory vault directly inside the TUI's Memory tab ('=' key), with all changes flowing through the pending queue for security.

• 📊 Dashboard & approvals upgrades. Richer live activity feeds, sparklines, write bars, colorized diffs, TTL badges, and batch approvals by agent or file with conflict-skip capability.

Looking for 1.2.0 (per-project memory, remote keep-alive, auto-capture), Semantic Recall from 1.1.0, or past Windows fixes? See the CHANGELOG for the full history.

Related MCP server: agent-memory

Contents

• Why Auxly

• How it works

• Install

• Uninstall

• Quick start

• The memory vault

• Memory insights & review

• Trust & access control

• Skills (slash commands)

• Supported agents

• Setup guide

• The dashboard

• Remote memory over SSH

• Live Usage

• Statusline (Claude Code · Cursor · Antigravity)

• Git sync

• Connect any MCP agent

• Command reference

• Configuration

• Security & privacy

• Contributing

• License

Why Auxly

The problem

Every AI agent keeps its own memory in its own walled garden. Tell Claude your stack, then open Codex — it knows nothing. Switch to Gemini — start over. Your context is fragmented across a dozen tools, none of them talk to each other, and none let you see or correct what they "remember" about you.

What Auxly does

Auxly gives all of your agents one memory — a folder of Markdown files on your own machine — and wires every agent to it through the Model Context Protocol (MCP). Teach one agent something once; every other agent knows it instantly. Because the memory is plain Markdown under your control, you can read it, edit it, diff it, and version it in Git like any other file.

The benefits

How it works

Auxly is a single static Go binary that plays three roles at once:

flowchart LR
    agents["Claude · Codex · Gemini<br/>Copilot · Cursor · any CLI agent"]:::agents
    mcp["MCP server<br/>stdio: read · write · search · sync"]:::core
    gate{"Trust gate<br/>auto · approve · read-only"}:::gate
    vault[("~/.auxly/memory/*.md")]:::store
    audit["Audit log<br/>JSONL + SQLite index"]:::audit
    git["git push (optional)"]:::ghost

    agents -->|MCP over stdio| mcp
    mcp --> gate
    gate -->|accepted write| vault
    vault --> audit
    vault -.-> git

    classDef agents fill:#917FD1,stroke:#B7A8F0,color:#ffffff,stroke-width:1px;
    classDef core fill:#73CBAD,stroke:#A7E6D2,color:#08231B,stroke-width:1px;
    classDef gate fill:#D97757,stroke:#F0A988,color:#ffffff,stroke-width:1px;
    classDef store fill:#84DCFB,stroke:#BDEEFD,color:#08231B,stroke-width:1px;
    classDef audit fill:#775099,stroke:#A88FCB,color:#ffffff,stroke-width:1px;
    classDef ghost fill:#2A2540,stroke:#917FD1,color:#D7D0F2,stroke-width:1px,stroke-dasharray:4 3;
    linkStyle default stroke:#8E7BD0,stroke-width:1.5px;

1. MCP server — auxly mcp-server exposes tools (read, write, search, sync, …) to any MCP-capable agent over stdio. Agents call them like any other tool.

2. Trust gate — every write is checked against the writing provider's trust level: write directly, queue for human approval, or reject.

3. Memory vault — accepted writes land as Markdown in ~/.auxly/memory/, optionally auto-committed to Git.

4. Audit — every access is recorded to an append-only JSON Lines log and indexed in SQLite for instant querying in the dashboard.

The only persistent files are Markdown in ~/.auxly/memory/ and two local SQLite indexes — the audit log and (optionally) the semantic index. There are no background daemons and no mandatory network calls — semantic recall uses a local embedding model by default and cloud is opt-in.

Install

macOS & Linux

curl -fsSL https://auxly.io/cli | sh

Install and wire up your local agents in one go:

curl -fsSL https://auxly.io/cli | sh -s -- --setup

Windows (PowerShell)

irm https://auxly.io/cli.ps1 | iex

Homebrew

brew install Tzamun-Arabia-IT-Co/homebrew-tap/auxly

npm

npm install -g auxly-cli

The npm package is a thin wrapper: on install it downloads the matching prebuilt binary for your platform and verifies it against the signed checksum manifest before vendoring it. Set AUXLY_ALLOW_UNSIGNED=1 only if you knowingly install a release that predates signing.

pip

pip install auxly-cli

Same model as the npm package — the wheel fetches and signature-verifies the platform binary on first run, then caches it. AUXLY_ALLOW_UNSIGNED=1 opts out of the strict check.

Go

go install github.com/Tzamun-Arabia-IT-Co/auxly-memory-cli@latest

From source

git clone https://github.com/Tzamun-Arabia-IT-Co/auxly-memory-cli.git
cd auxly-memory-cli
make build         # produces ./auxly
# Apple Silicon dev builds: codesign --force --sign - ./auxly

Prebuilt binaries, .deb, and .rpm packages are on the Releases page. Binaries are CGO-free single files — nothing to extract, no shared libraries to install.

Uninstall

Auxly is a single static binary plus a ~/.auxly data directory — no system services to scrub unless you ran auxly host setup (which installs a per-user keep-alive). The steps below remove the binary, the keep-alive (if any), and your local data.

⚠️ ~/.auxly holds your memory vault (~/.auxly/memory) on your main machine. Only delete it on a consumer box (one that just uses another machine's memory over SSH), or after exporting your vault. On a consumer box ~/.auxly only holds connection config — safe to delete. Export first with auxly export if unsure.

If the machine is wired to an agent, un-wire it first (removes the MCP launcher + /auxly-* skills) while the binary still exists:

auxly connect disconnect <name> --purge      # <name> = the saved profile, see `auxly connect list`

macOS & Linux

# Remove the keep-alive service if you were a memory HOST (no-op otherwise)
auxly host down 2>/dev/null || true
# macOS launchd leftover:
rm -f ~/Library/LaunchAgents/io.auxly.host.plist
# Linux systemd-user leftover:
systemctl --user disable --now auxly-host.service 2>/dev/null || true
rm -f ~/.config/systemd/user/auxly-host.service

# Remove the binary (whichever path it installed to)
sudo rm -f /usr/local/bin/auxly
rm -f ~/.local/bin/auxly

# Remove local data/config  (see vault warning above)
rm -rf ~/.auxly

Windows (PowerShell)

# Un-wire agent + skills, then remove host keep-alive task (no-op on a consumer box)
auxly connect disconnect <name> --purge 2>$null
schtasks /End /TN "Auxly-Host" 2>$null;  schtasks /Delete /TN "Auxly-Host" /F 2>$null

# Delete the binary + per-user install dir
$dir = Join-Path $env:LOCALAPPDATA 'Programs\auxly'
Remove-Item -Recurse -Force $dir -ErrorAction SilentlyContinue

# Strip it from your per-user PATH
$p = [Environment]::GetEnvironmentVariable('Path','User')
[Environment]::SetEnvironmentVariable('Path', (($p -split ';' | Where-Object { $_ -and $_ -ne $dir }) -join ';'), 'User')

# Delete local data/config  (see vault warning above)
Remove-Item -Recurse -Force "$env:USERPROFILE\.auxly" -ErrorAction SilentlyContinue

Homebrew

brew uninstall auxly
rm -rf ~/.auxly      # data is not removed by brew (see vault warning above)

After uninstalling, restart your terminal and any AI agent so the dropped MCP launcher and PATH change take effect.

Quick start

Auxly is built around one command — just run auxly:

auxly

• First run walks you through a short setup wizard and creates your memory vault.

• Every run after that opens the full-screen dashboard.

That's the whole entry point — there's no separate "init" or "ui" step to remember (those exist as explicit aliases, but you never need them).

Next, connect your AI agents to the shared memory:

auxly setup

This detects every AI agent installed on your machine (Claude, Codex, Gemini, Cursor, Antigravity, …) and wires each one to Auxly via MCP — plus installs the /auxly-* slash commands. No manual config editing.

Now, inside any connected agent's chat, start teaching it:

/auxly-init                  # scans the conversation and seeds your memory
/auxly-sync  I prefer pnpm and deploy on Vercel
/auxly-memory                # shows the profile every agent now shares

From here on, save one thing with /auxly-sync <topic> or harvest a whole session with /auxly-max — and every other agent picks it up automatically. Agents save the odd fact on their own now and then, but to keep your usage light they're not aggressive about it — so run these yourself whenever you want to be sure (see Keeping your memory in sync).

The memory vault

Your memory lives in ~/.auxly/memory/ as human-readable Markdown, organized by topic. Smart sync files each new fact under the right category — the agent picks the best-fit category from the taxonomy, with a keyword router as fallback when it's unsure:

~/.auxly/memory/
├── identity.md        # who you are, role, expertise
├── personal.md        # private life facts (family, health, finances) — never shared to a remote unless you grant it
├── preferences.md     # how you like your agents to work
├── infra.md           # machines, networks, environments
├── products.md        # products & services you build
├── projects.md        # active work, goals, constraints
├── business.md        # business / organizational context
├── daily.md           # recent, time-bound notes
├── agents.md          # registry of connected agents
├── CLAUDE.md · CODEX.md · GEMINI.md · …   # per-agent instruction files
├── trust.yaml         # per-provider access control
├── git.yaml           # Git sync configuration
├── .audit.log         # append-only audit trail (JSON Lines)
├── audit.db           # SQLite index of the audit log
└── .pending/          # writes awaiting your approval

Edit any of these by hand at any time — Auxly treats the files as the source of truth.

Memory insights & review

Auxly makes memory visible and self-maintaining — the vault tracks which facts agents actually use (hashes only, never query text), ages out stale facts through a human-approved review queue, and flags cross-file contradictions.

auxly stats --recall

auxly stats --recall

• Per-file hit tables — recall counts over the last 7/30/90 days, broken down file by file.

• Dead files — files with zero recall hits, the first candidates for pruning.

• Hot facts — the individual facts pulled into context most often.

• Fallback rate — how often recall falls back to keyword search instead of embeddings, a quick read on embeddings health.

Only fact hashes are stored in audit.db — never the query text — so a recalled secret can never leak into analytics.

auxly review

auxly review surfaces facts that are both old and unrecalled — untouched for 90 days by default, tunable with AUXLY_REVIEW_AGE_DAYS.

auxly review                # walk the queue interactively, fact by fact
auxly review --keep-all     # re-stamp every flagged fact and move on
auxly review --archive-all  # archive every flagged fact

• Keep re-stamps the fact's date via a first-seen ledger (consolidation rewrites do not reset fact age), so it won't come up for review again until it's stale once more.

• Archive moves the fact into .archive/ — never deleted, still plain text, still greppable.

• personal.md is excluded by default; pass --include-personal to include it too.

• Same queue lives in the dashboard's Review tab (-) — K keeps, a archives. All actions are audit-logged.

auxly organize --contradictions

auxly organize --contradictions embeds your facts and pairs up suspiciously-similar ones across files, then has an LLM judge each pair as a contradiction, duplicate, or distinct. Resolutions land in the normal pending queue tagged with the model's reason — review them first with auxly pending, then auxly approve <name> to see each diff. Bulk auxly approve --agent organize-contradictions applies every queued resolution without a preview, so only run it after you've reviewed. The pass needs an embeddings provider configured to run. When contradicted, facts are superseded with a dated trace and never erased.

Memory Browser (=)

The full vault can be browsed and edited directly inside the TUI's Memory tab by pressing =. Every edit or deletion flows through the pending queue for verification, and duplicate-content deletions are rejected.

Recall Playground (?)

Press ? in the TUI's Memory tab to launch the recall playground. Run any query through the real recall pipeline with visual score bars, floor cuts, and press Tab to cycle through client provider ACL lenses to see exactly what each connected client is permitted to view. Experimental queries in the playground never pollute analytics.

Trust Auto-Tuning (auxly trust suggest)

Approve/reject decisions accumulate as evidence. The auxly trust suggest command (also surfaced in auxly doctor and TUI settings) proposes promoting agents to auto (when at least 50 writes have been decided and at least 95% approved) or demoting them to read_only (when 30% or more are rejected). You can opt out via setting tuning: off in config.

Everything above is read-only until a human approves it — analytics never mutate the vault.

Trust & access control

You decide what each provider is allowed to do. Trust levels live in trust.yaml:

auxly trust list                       # show current levels
auxly trust set claude auto            # trust Claude to write directly
auxly trust set codex require_approval # review Codex's writes first
auxly trust set copilot read_only      # let Copilot read but not write

Pending writes show up as reviewable diffs in the dashboard's Approvals tab — approve or reject with a keystroke.

Skills (slash commands)

auxly setup installs 10 slash commands into every agent it configures. They work natively inside the agent's chat:

Under the hood these map to MCP tools (auxly_skill_sync, auxly_memory_read, auxly_memory_write, auxly_memory_search, auxly_memory_recall, auxly_pending_list, …) that any MCP client can call directly. auxly_memory_recall is the semantic search tool — call it directly from any MCP client for meaning-based lookup without running a skill.

Keeping your memory in sync — run these yourself

By design, Auxly's agents are lightly nudged to keep memory updated — never aggressively. An agent may save something on its own from time to time when it notices a clearly important fact, but it deliberately won't mine every message in the background, because constant background syncing would steadily consume your tokens. Since that occasional auto-sync is best-effort, not guaranteed, the reliable way to capture what matters is to run one of these yourself whenever you want to be sure:

• /auxly-max — whenever you feel a session produced something worth keeping, run this to harvest the entire session into the vault (one category at a time; private facts go to personal.md). Best at the end of a working session or before you switch context.

• /auxly-sync <topic> — to push one specific thing right now — a decision, a preference, a config value, a fact — without harvesting everything. The agent files it under the best-fit category automatically.

Rule of thumb: /auxly-max = "save the whole session," /auxly-sync <topic> = "save just this." Both are push-only and safe to run as often as you like.

A more thorough, guaranteed token-aware auto-capture that works across every connected agent — not just Claude — is on the roadmap. Until then, the occasional self-sync stays light to protect your usage, and these two commands are the reliable way to keep your memory current.

Supported agents

auxly setup auto-detects what you have installed and writes the MCP configuration for each — no manual JSON editing:

For each agent, Auxly also drops a workspace rules file (.clauderules, .cursorrules, .geminirules, …) so the agent knows to keep your memory in sync.

Setup guide

Automatic setup (recommended)

auxly setup

This detects every supported agent on your machine, writes each one's MCP configuration, installs the /auxly-* slash commands, and drops a workspace rules file so the agent keeps your memory in sync. Re-run it any time you install a new agent — it's idempotent and only updates what's needed.

Verify a connection from inside the agent's chat:

/auxly-status

…or just open the dashboard (auxly): every connected agent appears on the grid, and its reads/writes show live in the Activity tab.

Claude Desktop skills (one manual step)

Claude Desktop is the only agent that needs a manual touch. auxly setup wires its MCP connection automatically, but Claude Desktop doesn't load skills from disk — so the /auxly-* slash commands have to be imported once:

1. Run auxly setup. It exports the skills to ~/Downloads/auxly-skills-v<version>/ as ready-to-import .zip files — one per skill.

2. Open Claude Desktop → Settings → Capabilities → Skills (older builds: Settings → Skills).

3. Add each .zip from that folder (use Upload skill / drag-and-drop). You only do this once.

4. Restart Claude Desktop if the new skills don't show up right away.

The export folder is version-stamped (…-v<version>/), so when a release updates the skills you'll know to re-import the new set. (Every other agent — Claude Code, Codex, Gemini, Cursor, … — picks up skills automatically; this import step is Claude-Desktop-only.)

Connect any other MCP agent

auxly setup covers the agents listed above. Any other tool that speaks MCP — Android Studio, Perplexity, a homegrown client — can share the exact same memory with a one-time copy-paste config. The full walkthrough with the ready-to-paste JSON is at the end of this README:

➜ Connect any MCP-capable agent (manual setup)

The dashboard

auxly opens a fully interactive terminal UI. Drive it with the mouse — click tabs, agent cards, files, and buttons, and scroll lists — or the keyboard, whichever you prefer. And everything Auxly does is available two ways: as a scriptable CLI command (great for automation and muscle memory) and as a point-and-click action in the TUI. Same capabilities, your choice of interface.

The TUI has ten tabs:

The agent grid is dynamic — it shows only the agents detected or active on this machine, so it stays readable whether you run two agents or twenty. Any agent that connects and writes appears automatically (even one wired by hand); hide the ones you don't want to see under Settings → Agents.

Mouse or keyboard — your call. The TUI is fully mouse-aware: click a tab, an agent card, a file, or a button, and scroll through lists. Prefer keys? 1–9/0 jump tabs, ↑/↓ or j/k navigate, Tab/[/] cycle, Enter opens or confirms, q quits — and [u] pops the live usage panel from anywhere. Anything you can do here you can also do from the command line, and vice-versa.

The Audit Trail tab (0): every read and write — local and SSH-remote — with a Type filter.

Memory Organization

The Memory Org tab (5) runs an AI pass that consolidates and re-files your memory vault — deduplicating facts, moving misplaced lines to the right category, and tidying each file — without writing anything until you approve it.

1. Pick a provider + model. Any installed CLI agent (Claude, Codex, Gemini, Cursor, Antigravity) runs headless on your existing subscription — no API key. Or choose a local/API endpoint (Ollama, OpenAI, Gemini, or any OpenAI-compatible Custom URL, with models auto-fetched). The idle screen shows roughly how many tokens and files will be sent before you launch.

2. Run. The model reorganizes a copy of your vault in an isolated, read-only sandbox. Press esc any time to cancel the run.

3. Review every change. A two-pane before/after diff per file, color-coded by added/removed lines. Approve (a), reject (r), or edit (e) each file; A approves all. Approving auto-advances to the next file.

4. Submit. Only the files you approved are written. A confirmation screen lists exactly what changed, and every write is recorded in the Audit Trail (tagged Memory Org) so you have durable history.

Scope & safety: organize only ever touches your user-memory files. Agent setup/instruction files (agents.md, CLAUDE.md, AGENTS.md, providers.md, …) are never read or rewritten. Nothing is saved until you approve, and the agent runs with no tools, an empty working directory, and a scrubbed environment so it can never reach your real vault on its own.

Remote memory over SSH

Run your agents on a server, a NAT'd box, or another laptop while keeping one memory host as the source of truth — over plain SSH. There is no daemon, no open listening port, no auth token, and no custom protocol. A remote session is literally:

ssh host auxly mcp-server

The agent on the remote machine spawns that over SSH and speaks MCP over stdio; the host serves its memory and audits every access as if it were local. Anything that gives you ssh host already gives you Auxly — bring your own LAN, VPN, bastion, or relay.

Two roles

flowchart LR
    subgraph consumer["CONSUMER box"]
        c["your agent runs here<br/>auxly connect …"]:::node
    end
    subgraph host["MEMORY HOST"]
        h["memory lives here<br/>audits every access"]:::node
    end
    c -->|"ssh host auxly mcp-server"| h
    h -.->|"memory over stdio"| c

    classDef node fill:#73CBAD,stroke:#A7E6D2,color:#08231B,stroke-width:1px;
    style consumer fill:#241F38,stroke:#917FD1,color:#D7D0F2,stroke-width:1px;
    style host fill:#241F38,stroke:#84DCFB,color:#BFE9FB,stroke-width:1px;
    linkStyle default stroke:#8E7BD0,stroke-width:1.5px;

Connecting a machine to a host

On the consumer box, run the wizard and pick how the two machines reach each other:

auxly connect          # wizard: relay / LAN / VPN / bastion / public
auxly connect list     # show configured hosts + connected boxes
auxly connect auto     # one-command bootstrap when a host advertises an offer

The wizard's steps are method → host → name → permissions → connect. For a relay connection (the first option — serve this machine's memory to a NAT'd box), the permissions step lets you pick what the box may access per file — Off / Read / Read+Write (←/→ to cycle, a all-read, n none) — before it connects. Non-personal files default to Read+Write; personal.md is Off with an exposure warning. Consumer methods (LAN/VPN/bastion/public) only read the remote's memory, so they skip the permissions step.

auxly connect auto also carries your setup onto the new machine: it wires the MCP launcher + skills and installs the Auxly statusline for that box's detected agents (idempotent — a machine with its own statusline is left alone). To keep a remote on the latest release automatically, enable Auto-Update in Settings (or set "autoUpdate": true in ~/.auxly/settings.json) — each machine then self-updates in place after a session, so a publish reaches every box without a manual auxly update.

Connecting to a host whose auxly is older than yours? Add --update-remote (or set "updateRemotesOnConnect": true) and connect bumps it in place over the same SSH and ensures its statusline — driven from your already-updated side, so it works even when the remote is too old to self-update. A host serving a live session is skipped (it updates on its next idle connect), so a running relay is never interrupted.

Managing your boxes from the host. The Remote tab shows each connected box's memory permission (read-only / read+write / read+write·Nf) and flags any box running an older auxly with a ⬆ 1.0.10→1.0.11 badge. Press u on a box to update it over SSH, or B on the Dashboard to update every outdated box at once (live boxes are skipped). When the outdated boxes are all busy, f force-updates them too (ending their live session). The same is scriptable: auxly host versions and auxly host update <name>|--all [--force]. To grant write access to your fleet without per-box setup, enable "defaultRemoteWrite": true — known boxes (in clients.yaml) then default to read+write, while unknown remotes stay read-only and explicit per-file grants still win.

Push your statusline to the fleet. When you update a box (or sync from Settings → Customizations, press s), its statusline is installed in the same wrap-vs-replace mode you use locally. If you run Live Usage, the box's plan-usage line is primed during the sync (via the box's own statusline --refresh-usage) so it renders on the next draw — even on a box too old to persist the opt-in. The sync manager offers a master auto-sync toggle, per-box include/exclude, and sync-now (all boxes or one at a time).

Auxly is network-agnostic and stores no network credentials — you bring the reachability, it rides on top:

Serving your memory to NAT'd boxes (relay)

If a box can't reach your machine directly (it's behind NAT), your machine opens an outbound reverse tunnel through a relay you both can reach, and the box reaches your memory through it. On the host:

auxly host setup       # open the reverse tunnel via a relay; provision the box
auxly host status      # every served box + its live tunnel state
auxly host clients     # list connected boxes
auxly host down        # stop serving

Multiple boxes stay connected at the same time — each gets its own independent, self-healing tunnel, supervised by a single keep-alive. Connecting one box never disconnects another.

One-command pairing

Pairing a consumer machine with a memory host is as simple as generating an invite token on the host and joining from the client. Note that the joiner must already have SSH login access to the host; the invite authorizes the Auxly memory pairing, not OS-level user access.

1. On the host, run auxly host invite (or press i in the TUI's Remote tab). This mints a secure, single-use token pinned to the host's SSH public key, complete with a configurable time-to-live (TTL). You can manage invites with auxly host invite --list and auxly host invite --revoke.

2. On the consumer, run auxly join <token>.

The join command connects to the host, verifies the host key pin directly on the connection carrying the secret (utilizing temporary known_hosts and StrictHostKeyChecking=yes for injection safety), provisions the consumer via the existing self-test path, and atomically burns the invite token on the host. Token fields are strictly validated and shell-quoted as hostile input to prevent exploit vectors.

Choose what each box can see

A remote never gets your whole vault by default — every served box carries its own per-remote file-sharing allow-list. You set it at connect time in the relay wizard's permissions step, and you can change it anytime: in the dashboard's Remote tab, highlight a connected box and press s to open its Share files checklist (listed in taxonomy order), then toggle individual files and set Off / Read / Read+Write for that box specifically.

It's fail-closed for what matters: personal.md (and the aggregate profile) are never shared unless you explicitly turn them on, and an unmatched/unknown remote is never granted write. So a trusted laptop can be a full read+write peer while a CI box sees only projects.md read-only — and your private life facts stay on your machine.

See where writes come from

Sessions opened from a remote machine appear in the Activity and Audit Trail tabs tagged SSH-remote, annotated with the connecting client's IP and OS — so you always know which writes came from a remote agent versus a local one. auxly connect also runs an OS-aware doctor that installs auxly on a macOS/Linux host automatically (and prints guided steps on Windows), so linking a new machine is usually a single command.

Live Usage

Auxly can show each agent's live subscription quota — session and weekly usage — right in the dashboard, by reusing each agent's own locally-stored login token. It reads:

• Claude / Claude Code, Codex (ChatGPT) — session & week %, plus plan/tier

• Gemini, Antigravity — overall quota %

• Cursor — local AI-code activity (no network call)

This is the only feature that makes outbound network calls, it is off by default, and you enable it in Settings. Tokens are never logged, cached, or forwarded; each provider is called only for its own usage. Antigravity needs a one-time login:

auxly usage show              # print quota for every agent
auxly usage auth antigravity  # one-time browser consent for Antigravity

Session and weekly quota for every connected agent, reusing each one's own login — no API key.

Statusline (Claude Code · Cursor · Antigravity)

Auxly ships a productized statusline for Claude Code, Cursor CLI, and Antigravity CLI — a rich, multi-line status bar that surfaces your working context, your memory link, and your live plan usage without leaving the editor. Wire it into one agent or all of them (additive and fully reversible — each agent's existing statusline, even a hand-rolled statusline.sh, is backed up and restored on uninstall):

auxly statusline install                       # Claude Code (default)
auxly statusline install --agent cursor        # Cursor CLI
auxly statusline install --agent antigravity   # Antigravity CLI
auxly statusline install --agent all           # every detected agent at once
auxly statusline install --wrap                # keep your own statusline and append the Auxly segment
auxly statusline uninstall --agent <name>      # restore that agent's backed-up original

It renders four lines: where (folder · branch · model · version), session (thinking/params · effort · tokens · context bar), Auxly memory (link · role · last op · pending), and live plan usage for whichever agent renders it — Claude's 5h + weekly bars, Cursor's plan/auto, or Antigravity's overall, each with reset countdowns. Each provider reads only its own usage cache, so one agent's numbers never bleed into another's line.

The render path never makes a network call — it reads only the last-good usage snapshot on disk, so it's safe to run on every prompt. When Live Usage is enabled, the usage line stays live during an active session: after printing instantly it triggers a guarded, detached background refresh that updates the snapshot for the next render (debounced, and rate-limited by the same circuit breaker as the dashboard). You can also manage it in the dashboard under Settings → Customizations, where an agent switcher (a to cycle) gives each agent its own replace/wrap/none choice with a live preview before you apply; applying one auto-advances to the next agent, and an agent already running Auxly offers Restore my original statusline from the backup.

Each agent is wired in its own config file, and the installed command carries a --provider flag so the right plan usage shows:

Agents without a scriptable statusline (Codex, Gemini CLI) aren't wired — your memory still works everywhere.

Settings → Customizations: switch agents (Claude · Cursor · Antigravity) and pick each one's statusline mode with a live preview before applying.

Auto-capture (opt-in)

Let sessions teach your memory without lifting a finger. auxly capture extracts durable facts from a session transcript with your configured LLM, dedups them against the vault, and queues them as pending changes — it never writes memory directly, so you review everything with auxly pending.

auxly hooks install     # Claude Code: adds a Stop hook running `auxly capture`
auxly hooks uninstall   # removes exactly that hook, touching nothing else

Throttled by design: sessions under ~2K tokens are skipped, at most one capture per 10 minutes, at most 10 facts per run.

Every agent, one command:

auxly hooks status shows what's actually wired right now, agent by agent. Honest caveat: Gemini and Kimi have no session-end hook, so their wrappers capture raw terminal output via script, not a structured transcript — still enough signal to extract durable facts from. Codex capture reads conversation messages only — function calls, tool output, and reasoning traces are filtered out before anything reaches the extraction LLM.

Git sync

Your memory is a folder — so version it. Auxly auto-commits on write and pushes only when you ask:

auxly sync     # commit + push to your configured remote

# git.yaml
auto_commit: true
auto_push: false
commit_message_prefix: "auxly:"
branch: main

Connect any MCP-capable agent (manual setup)

Auxly is a standard stdio MCP server, so any MCP-capable tool can share the same memory — even ones Auxly doesn't auto-detect, or whose config lives somewhere auxly setup can't write (Android Studio's Gemini settings sync to your Google account, for example). It's the same three pieces everywhere.

1. Add the server entry wherever your agent keeps MCP servers — its config file, or an "Add MCP server" dialog:

{
  "mcpServers": {
    "auxly-memory": {
      "command": "/absolute/path/to/auxly",
      "args": ["--path", "/Users/you/.auxly/memory", "mcp-server"],
      "env": {
        "AUXLY_MEMORY_PATH": "/Users/you/.auxly/memory",
        "AUXLY_PROVIDER": "your-agent-id"
      }
    }
  }
}

2. Fill in the three values:

3. Reload the agent. Some clients pick the server up instantly; others need a restart or a one-time "approve this server" before the tools go live.

4. Verify. From the agent's chat run /auxly-status (if it has skills), or just open auxly — the moment the agent connects and writes, it appears on the dashboard grid, is labeled by its AUXLY_PROVIDER id in the Audit Trail, and can be hidden or re-shown under Settings → Agents.

Schema variations: most clients use the { "mcpServers": { … } } wrapper above (Claude Desktop, Warp, Void, Cursor, JetBrains AI Assistant, …). A few accept only the inner { "auxly-memory": { … } } object — if the wrapped form is rejected, paste just the inner block. On Windows, use a full path with escaped backslashes ("C:\\Users\\you\\auxly.exe") or a forward-slash path.

App-specific entry points: Android Studio → the Gemini "Configure MCP servers" dialog, or JetBrains AI Assistant → Settings → MCP (which can also Import from Claude once you've run auxly setup). Perplexity and most desktop clients → their Settings → Connectors / MCP panel.

Command reference

Configuration

Auxly is config-light: it works with zero setup, and everything it does persist lives under ~/.auxly/ as plain text you can read, edit, and version.

Config files

All optional — Auxly creates and manages these for you; edit them by hand any time.

Environment variables

Auto-update polls auxly.io/version and, when a newer release exists, prints a one-line notice; auxly update performs a one-click self-update from the official release channel.

Security & privacy

• Local-first. Memory lives only on your machine; nothing is uploaded unless you push to your own Git remote.

• No telemetry. Auxly phones home only for version checks and the opt-in Usage feature.

• Credentials stay put. Auxly stores no SSH keys, VPN config, or network secrets. Usage tokens are read in place and never persisted or logged.

• Auditable by design. Every read and write is recorded with who/what/when/why and reviewable in the dashboard.

• You hold the keys. Trust levels and the approval queue mean no agent writes anything you didn't allow.

Vault encryption at rest

Auxly supports file-level encryption at rest for the memory vault using the age X25519 standard. This ensures that Git sync commands can securely ship ciphertext without exposing your secrets, as the keys reside outside the vault.

• Initialization & Keys: Run auxly encrypt init to generate a key. The key is securely stored in the macOS Keychain (using stdin via security -i to avoid command-line argument exposure) or falls back to a 0600 permissions file outside the vault. A backup key is printed once during initialization with a hard warning. Keys cannot be overwritten once set to prevent orphaned ciphertext.

• Commands: Manage encryption with auxly encrypt file <name>, auxly decrypt file <name>, and auxly encrypt status. Once encrypted, an age header in the file ensures all future writes stay encrypted automatically.

• Security & Fail-Closed: The implementation is strictly fail-closed: decryption failures never fall back to treating files as empty, CLI-agent organization commands are refused for encrypted content, backups and archives keep the ciphertext encrypted, and auxly export skips encrypted files (with a manifest note) rather than writing plaintext copies. The sqlite recall index is pruned and VACUUMed on encryption; recall commands will report how many encrypted files were excluded from search.

• v1 Limitations: While the vault files themselves are encrypted, current workspace copies of memory files and transient diffs in the pending queue (.pending/) are handled in plaintext (secured with local 0600 file permissions).

Found a vulnerability? See SECURITY.md for private disclosure.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the build, test, and PR flow, and our Code of Conduct.

make build && go test -race ./...

License

MIT © Tzamun Arabia IT Co.