Metadata-Version: 2.4
Name: aptuni
Version: 0.1.0
Summary: Aptuni — a local-first personal context layer that grows more attuned to you over time.
Project-URL: Homepage, https://github.com/ruihaomei/aptuni
Project-URL: Repository, https://github.com/ruihaomei/aptuni
Project-URL: Issues, https://github.com/ruihaomei/aptuni/issues
Project-URL: Changelog, https://github.com/ruihaomei/aptuni/blob/main/CHANGELOG.md
Author: MEI Ruihao
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Keywords: ai-agents,context-engineering,local-first,mcp,memory,personal-context
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.13
Requires-Dist: mcp==2.2.0
Requires-Dist: pydantic<3,>=2.11
Description-Content-Type: text/markdown

<p align="center"><img src="https://raw.githubusercontent.com/ruihaomei/aptuni/v0.1.0/assets/brand/logo/aptuni-icon.svg" width="120" alt="Aptuni"></p>

<h1 align="center">Aptuni</h1>
<p align="center"><b>Context, attuned to you.</b></p>
<p align="center">Personal context · Memory · MCP · Local-first</p>
<p align="center"><a href="https://github.com/ruihaomei/aptuni/blob/v0.1.0/README.zh-CN.md">简体中文</a> · <a href="https://github.com/ruihaomei/aptuni/blob/v0.1.0/LICENSE">Apache-2.0</a> · v0.1.0 pre-alpha</p>

**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](#what-works-today) and the
> [roadmap](https://github.com/ruihaomei/aptuni/blob/v0.1.0/docs/dev/ROADMAP.md).

## 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](https://docs.astral.sh/uv/):

```sh
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`](https://github.com/ruihaomei/aptuni/blob/v0.1.0/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:

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

```sh
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:

```sh
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

| Area | Status |
|---|---|
| Profile Vault: facts, history, corrections, crash-safe writes, `doctor` | ✅ |
| Module permissions (ingest / expose, independently) | ✅ |
| Folder source (Markdown, text, CSV) with incremental sync and provenance | ✅ |
| GitHub source, Standard mode (bounded, exact commit provenance) | ✅ |
| Bilingual (English + Chinese) local search, rebuildable index | ✅ |
| Layered context (L0 identity card → L4 evidence) with a budget | ✅ |
| MCP server over local STDIO, permission-checked reads and quarantined memory proposals | ✅ |
| Claude Code and Codex adapters | ✅ |
| Plugin Advisor, Recipes, English / 简体中文 CLI | ✅ preview (`aptuni advise`) |
| Verified backup and restore of the canonical Vault | ✅ |
| MarginNote 4 source (macOS, direct read-only local sync, native IDs) | ✅ |
| Obsidian source and UI, Mem0, hybrid retrieval, Graphiti | 🗺 Milestones 2–3 |

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

## How it works

```text
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/`](https://github.com/ruihaomei/aptuni/blob/v0.1.0/docs/dev/DECISIONS/README.md), and the product
requirements in [`docs/product/PRD.md`](https://github.com/ruihaomei/aptuni/blob/v0.1.0/docs/product/PRD.md).

## Recipes

| Recipe | For | Needs |
|---|---|---|
| **Starter Lite** | Just make it work | nothing extra |
| **Researcher** | Notes, documents and code as knowledge evidence | optional `GITHUB_TOKEN` |
| Personal Memory | Learn from everyday conversations | Milestone 2 (Mem0) |
| Temporal Memory | Relationships that change over time | Milestone 3 (Graphiti) |

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`](https://github.com/ruihaomei/aptuni/blob/v0.1.0/SECURITY.md) and the [threat model](https://github.com/ruihaomei/aptuni/blob/v0.1.0/docs/dev/THREAT_MODEL.md).

These commands make that concrete:

```sh
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:

```sh
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`](https://github.com/ruihaomei/aptuni/blob/v0.1.0/CONTRIBUTING.md). Adding a plugin to the Advisor catalog is one TOML file
plus two message lines.

## License

[Apache-2.0](https://github.com/ruihaomei/aptuni/blob/v0.1.0/LICENSE). Third-party notices are in [`THIRD_PARTY_NOTICES.md`](https://github.com/ruihaomei/aptuni/blob/v0.1.0/THIRD_PARTY_NOTICES.md).
