Aptuni

Context, attuned to you.

Personal context · Memory · MCP · Local-first

简体中文 · Apache-2.0 · v0.1.0 pre-alpha

Aptuni gives AI agents the right personal context without giving them everything about you. The more you use it, the better it understands what matters.

You stop re-explaining yourself to every agent. Your agent gets a small, relevant, verifiable slice of who you are for the task at hand, and you keep the whole thing in open files you own.

Status: pre-alpha (Milestone 1). The core runs end to end on supported macOS and Ubuntu 24.04/ext4 systems. Interfaces will still change. See what works now and the roadmap.

Why Aptuni

• Attunement over accumulation. Agents get the smallest useful context for a task, not a dump of everything stored about you.
• You own it. Your Profile Vault is plain JSONL/Markdown on your disk. Indexes and memory engines are rebuildable projections, so you never lose yourself when a backend changes.
• Evidence, not guesses. A document that mentions XGBoost is exposure, not expertise. Every claim keeps its source, time and history.
• Your switches. Each module (knowledge, experience, preferences…) has separate ingest and expose controls. "Don't tell my agent about my work history" hides it without deleting it.
• No extra API key required. The default setup needs no Docker, no vector or graph database and no model key. Claude Code or Codex can be the intelligence you already have.

Install with your agent

Install the public package with Python 3.13 and uv:

uv tool install aptuni==0.1.0
aptuni --version

Open this repository in Claude Code or Codex and say:

Read this repository and set up Aptuni for me.

The agent reads AGENTS.md, asks which language you prefer, then walks through what sources you have, how you want to be remembered, and whether cloud models may process your data.

You can drive the same flow yourself. It is two commands, and the first one creates only a private, expiring plan record — no Vault, source, grant, or host bundle:

aptuni setup plan --folder ~/Documents/notes --host claude_code
aptuni setup apply ACTION_ID       # you type APPLY in your own terminal

setup plan prints the recommended components and why, the API keys and setup time, exactly which of your modules an agent will be able to read and which operator receives them, the exact folders it will read, every file it will write and where, and the exact ordered steps — then stops. None of those effects happens until you confirm that one plan, and the confirmation is bound to its digest, so an edited plan can never be applied.

Aptuni writes the agent integration into its own directory and does not modify your host's configuration; you point the host at it yourself. If a step fails, the run stops there and resumes where it left off. aptuni setup cancel ACTION_ID revokes the agent access it granted and tells you exactly what remains — your Vault, sources and evidence are never deleted for you.

60-second manual quickstart

Requires the installed Python 3.13 package above.

aptuni advise                      # a few plain-language questions; changes nothing
aptuni init ~/Aptuni               # create your Profile Vault (or let `setup apply` do it)
aptuni remember "Prefers concise, structured technical explanations." --module preferences
aptuni source add-folder ~/Documents/cv --module experience --role application-materials
aptuni sync SOURCE_ID              # minimized evidence from files you approved
aptuni context "help me prepare for a data science interview" --module experience --evidence --budget 1500

Then connect an agent:

aptuni adapter plan claude --module identity --module preferences --allow-host-model-egress
aptuni adapter apply ACTION_ID     # you confirm in your own terminal

What works today

Run aptuni plugin list and aptuni recipe list to see the same picture from the CLI.

How it works

Sources ──► Evidence ──► Profile + Memory ──► Context ──► Agents
(folders,    (minimized,   (temporal facts,    (L0–L4,     (MCP, Claude Code,
 GitHub,      provenance)   your switches)      budgeted)    Codex)
 MarginNote)

• Profile ≠ Memory ≠ Context. A Profile changes slowly, memory forms quickly, and context is the task-specific slice assembled at runtime.
• Progressive disclosure. Agents start from a short identity card and ask for more only when a task needs it.
• Sources change safely. Every sync is an immutable snapshot plus a reviewable delta. A deleted file withdraws evidence; it never silently rewrites history. Ambiguous changes wait for you.

Design decisions live in docs/dev/DECISIONS/, and the product requirements in docs/product/PRD.md.

Recipes

You choose an experience; Aptuni chooses the components. Recipes that are not installable yet are shown with the closest working alternative.

Privacy in one paragraph

Aptuni never scans your machine on its own, and discovering a source does not mean it has permission to read it. Raw conversations are not kept by default. Agents see only modules you expose, within a budget, and the adapter preview tells you exactly what leaves your device (for example, context an agent reads is processed by that agent's model provider). See SECURITY.md and the threat model.

These commands make that concrete:

aptuni privacy status                  # every copy Aptuni manages, and the ones it cannot delete for you
aptuni privacy purge preview <id>      # the exact records and copies a deletion would remove
aptuni privacy purge confirm <action>  # irreversible, and only for that one preview
aptuni privacy purge cancel <action>   # abandon a confirmed purge that deleted nothing

privacy status names external copies plainly — exports you made yourself, your original source files, and transcripts held by an agent's provider — because Aptuni cannot delete those and will not pretend otherwise. The purge receipt reports, per copy, what actually happened.

Backups you can actually restore

aptuni export writes a readable copy of your current Profile. It is for reading, and it cannot be restored. The restorable copy is a backup:

aptuni backup create ~/aptuni-backups/2026-09-20   # a verified copy, outside your Vault
aptuni backup verify ~/aptuni-backups/2026-09-20   # checks it without touching your Vault
aptuni backup list   ~/aptuni-backups              # what you have, and whether each still verifies
aptuni backup restore preview <path>               # exactly what a restore would replace, drop and keep
aptuni backup restore confirm <action>             # only for that one preview

A backup is a complete unencrypted copy of your canonical records, including modules you have hidden, so where you keep it matters. Two things it will not do: it never resurrects a record you purged, on any machine, because deletions travel with your Vault; and it never overwrites a folder that already has files in it.

Contributing

Plugins, recipes, translations and bug reports are welcome. Start with CONTRIBUTING.md. Adding a plugin to the Advisor catalog is one TOML file plus two message lines.

License

Apache-2.0. Third-party notices are in THIRD_PARTY_NOTICES.md.