auxly-memory-cli

README

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.

---

Contents

• Why Auxly
• How it works
• Install
• Quick start
• The memory vault
• Trust & access control
• Skills (slash commands)
• Supported agents
• Setup guide
• The dashboard
• Remote memory over SSH
• Live Usage
• Git sync
• 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

	Benefit
🧠 Shared context	Say it once to any agent — all your other agents inherit it. No more re-explaining your stack, preferences, or projects per tool.
📂 You own the data	Memory is Markdown in ~/.auxly/memory/. Open it in any editor, grep it, commit it. Nothing is locked inside a vendor's cloud.
🔒 Local-first & private	No server, no telemetry, no embeddings, no Docker. Memory never leaves your machine unless you push it to a Git remote.
🛂 You stay in control	Per-agent trust levels decide whether a write lands instantly, queues for your approval, or is denied.
🧾 Fully auditable	Every read and write is logged append-only with who, what, when, and why — surfaced in a live dashboard.
🌐 Works across machines	Share one memory host with NAT'd servers and laptops over plain SSH — no daemon, no open port, no token.
🆓 Free & open	MIT-licensed Go binary. Single static file, zero runtime dependencies.

---

How it works

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

                ┌─────────────────────────────────────────────┐
   Claude  ─┐   │                  auxly                       │
   Codex   ─┤   │   ┌──────────────┐      ┌────────────────┐   │
   Gemini  ─┼──▶│   │  MCP server  │─────▶│  Trust gate    │   │
   Copilot ─┤   │   │ (stdio JSON- │      │ auto / approve │   │
   Cursor  ─┤   │   │   RPC tools) │      │  / read-only   │   │
   …any CLI─┘   │   └──────────────┘      └───────┬────────┘   │
                │                                  ▼            │
                │   ┌──────────────┐      ┌────────────────┐   │
                │   │  Audit log   │◀─────│  ~/.auxly/      │   │
                │   │JSONL + SQLite│      │  memory/*.md    │──┼──▶ git push
                │   └──────────────┘      └────────────────┘   │   (optional)
                └─────────────────────────────────────────────┘

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 "database" anywhere is a local SQLite file used purely to index the audit log. There are no embeddings, no background daemon, and no network calls in normal operation.

---

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

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.

---

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, anything any agent learns about you can be saved with /auxly-sync, and every other agent picks it up automatically.

---

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.

---

Trust & access control

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

Level	Behavior
auto	Writes land in memory immediately
require_approval	Writes queue in .pending/ for you to review and approve/reject
read_only	Provider can read but never write

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:

Skill	What it does
/auxly-init	Onboards you — runs the training, scans the current conversation/context, and seeds your memory with what's already known.
/auxly-sync <fact>	Saves a new fact, preference, or detail with a smart delta-merge — the agent files it under the best-fit category (with a keyword router as fallback).
/auxly-memory	Prints the consolidated profile (identity + preferences + infrastructure) every agent currently shares.
/auxly-learn [folder] [topic]	Reads the memory vault — optionally a single folder, optionally focused on a topic — and grounds the agent in it for the session. No args = learn everything.
/auxly-max	Exhaustive self-harvest — scans the whole session and writes every fact up into the vault, one category at a time (private facts go to personal.md). Push-only.
/auxly-forget [query]	Searches memory and cleanly prunes obsolete or outdated lines.
/auxly-pending [list|approve|reject]	Manages the approval queue from inside the chat panel.
/auxly-status	Shows whether the agent is connected and the MCP link is live, plus diagnostics.
/auxly-bootstrap	Generates a copyable onboarding block to paste into a tool that doesn't have Auxly installed (e.g. ChatGPT).
/auxly-remote-connect	Detects and connects this machine to a remote Auxly memory host (or reports the active link).

Under the hood these map to MCP tools (auxly_skill_sync, auxly_memory_read, auxly_memory_write, auxly_memory_search, auxly_pending_list, …) that any MCP client can call directly.

---

Supported agents

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

Agent	Integration
Claude Desktop	MCP server entry (+ importable skills — see Setup guide)
Claude Code (CLI)	claude mcp add + skills
Codex (IDE & CLI)	MCP + codex mcp add
Cursor (IDE & Agent CLI)	MCP + auto-approved tool allowlist
Gemini CLI	MCP server entry + skills
Antigravity (CLI / Agent / IDE)	MCP server entries
GitHub Copilot	shared memory via MCP/skills
Warp (terminal)	MCP — ~/.warp/.mcp.json
Void (editor)	MCP — ~/.void-editor/mcp.json
Windsurf, Kimi Code, Trae	MCP + workspace rules
Android Studio	MCP via the Gemini Agent or JetBrains AI Assistant — manual setup
Any MCP client / CLI agent	paste an MCP entry (manual setup) or call auxly read/write/search

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

Claude Desktop doesn't load skills from disk automatically — only the MCP connection is wired for you. auxly setup exports the slash commands to ~/Downloads/auxly-skills-v<version>/ as ready-to-import .zip files; add each one in Claude Desktop once (Settings → Skills). The export folder carries the version number, so when a release updates the skills you'll know to re-import. (Every other agent picks up skills automatically — this step is Claude-Desktop-only.)

Connect any MCP-capable agent (manual setup)

Auxly auto-wires the agents listed above, but any tool that speaks MCP can share the same memory — Android Studio, Perplexity, a homegrown client, anything. Some agents simply store their MCP config somewhere Auxly can't write to (Android Studio's Gemini settings sync to your Google account, for instance), or aren't auto-detected yet. Connecting one by hand is the same three pieces everywhere, because Auxly is a standard stdio MCP server.

1. Add the server entry wherever your agent keeps MCP servers — a config file, or its "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": "perplexity"
      }
    }
  }
}

2. Fill in the three values:

• command — your binary path, from which auxly (e.g. /usr/local/bin/auxly).
• --path / AUXLY_MEMORY_PATH — your vault folder; default ~/.auxly/memory.
• AUXLY_PROVIDER — a short id naming this agent (perplexity, android-studio, …). This is what the audit trail and dashboard attribute its writes by, so give every tool its own id — never reuse another agent's, or its writes get mislabeled.

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

That's it — the moment the agent connects and writes, it appears on the dashboard grid, is labeled correctly in the Audit Trail, and can be hidden or re-shown under Settings → Agents.

Schema note: 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.

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.

---

The dashboard

auxly opens a full-screen terminal dashboard:

#	Tab	What you see
1	Dashboard	Today's writes, pending approvals, and a live grid of your connected agents
2	Activity	Live audit feed, color-coded by provider, local vs. SSH-remote
3	Files	Browse, view, edit, and download your memory files
4	Approvals	Review pending diffs — approve or reject
5	Analytics	Writes per agent + (opt-in) live usage meters
6	Settings	Trust levels, on-demand memory organization, and Live Usage — plus an Agents sub-tab to show/hide which agents appear on the dashboard
7	Remote	Manage memory hosts and connected boxes over SSH
8	Skills	The installed slash commands at a glance
9	Audit Trail	Full, queryable history

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.

Keyboard-driven throughout: 1–9 jump tabs, ↑/↓ or j/k navigate, Tab/[/] cycle, q quits. Press [u] anywhere for the live usage popup.

---

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

   ┌────────────────────┐         plain SSH          ┌────────────────────┐
   │   CONSUMER box      │  ───────────────────────▶  │   MEMORY HOST       │
   │  (agent runs here)  │   ssh host auxly mcp-server │ (memory lives here, │
   │  auxly connect …    │  ◀───────────────────────  │  audits every write)│
   └────────────────────┘     memory over stdio        └────────────────────┘

Role	What it does	Command
Memory host	Serves the shared memory and audits every access	runs auxly mcp-server (invoked over SSH)
Consumer box	Where an agent runs; reaches the host's memory	auxly connect

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: LAN / VPN / bastion / public / relay
auxly connect list     # show configured hosts + connected boxes
auxly connect auto     # one-command bootstrap when a host advertises an offer

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

Method	When
LAN	Host and box on the same network
VPN	Your own overlay (Tailscale, WireGuard, …) — Auxly never configures it
Bastion	Reach the host through a jump host
Public	A reachable hostname/IP or custom SSH config entry
Relay	Serve a NAT'd box through a reverse tunnel you control

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.

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. 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 read vs. write access for that box specifically.

It's fail-closed: personal.md (and the aggregate profile) are never shared unless you explicitly check them, and the default for a newly connected box is all non-personal files, read-only. So a trusted laptop can read everything while a CI box sees only projects.md — 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

---

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

---

Command reference

Command	Description
auxly	First run: setup wizard. After that: open the dashboard.
auxly setup	Detect and wire every local agent (MCP + skills)
auxly list / view <file>	List or view memory files
auxly search <query>	Search across all memory
auxly write …	Write a change (used by agents/wrappers)
auxly trust list | set <provider> <level>	Manage access control
auxly tail	Stream the audit log
auxly stats	Memory & write statistics
auxly sync	Commit + push memory to Git
auxly connect …	Link this machine to a remote memory host
auxly host …	Serve this machine's memory to other boxes
auxly usage show | auth	Live agent quota (opt-in)
auxly mcp-server	Run the MCP server (invoked by agents)
auxly update	Self-update to the latest release

---

Configuration

Environment variables

Variable	Purpose
AUXLY_MEMORY_PATH	Override the memory folder location
AUXLY_INSTALL_BASE	Override the download/update base (default https://auxly.io)
AUXLY_PROVIDER	Override the provider id for a write
AUXLY_LLM_BASE	Override the LLM endpoint used by smart sync

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.

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.

<sub>Built with care by



auxly.io · your memory, every agent, on your machine</sub>