Metadata-Version: 2.4
Name: tawn
Version: 0.1.0
Summary: Tawn — the personal digital twin. Local-first memory and context core for your work, wealth, research, and academic life.
Author-email: Testimony Adekoya <testimonyadekoya.02@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/tawn-hq/tawn
Project-URL: Repository, https://github.com/tawn-hq/tawn
Project-URL: Bug Tracker, https://github.com/tawn-hq/tawn/issues
Keywords: ai,personal-ai,digital-twin,memory,mcp,rag,local-first,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: PyYAML>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.7
Requires-Dist: fastapi>=0.111
Requires-Dist: uvicorn>=0.30
Requires-Dist: keyring>=25.0
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: watchfiles>=0.21
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.100; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=2.0; extra == "openai"
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == "gemini"
Provides-Extra: ollama
Requires-Dist: ollama>=0.4; extra == "ollama"
Provides-Extra: vectors
Requires-Dist: pgvector>=0.3; extra == "vectors"
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0; extra == "mcp"
Provides-Extra: providers
Requires-Dist: anthropic>=0.100; extra == "providers"
Requires-Dist: openai>=2.0; extra == "providers"
Requires-Dist: google-genai>=1.0; extra == "providers"
Requires-Dist: ollama>=0.4; extra == "providers"
Provides-Extra: full
Requires-Dist: anthropic>=0.100; extra == "full"
Requires-Dist: openai>=2.0; extra == "full"
Requires-Dist: google-genai>=1.0; extra == "full"
Requires-Dist: ollama>=0.4; extra == "full"
Requires-Dist: pgvector>=0.3; extra == "full"
Requires-Dist: fastmcp>=2.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Dynamic: license-file

# Tawn — the twin you own

> **taw (ת) + own** — Local-first personal digital twin. Your data, your machine, your intelligence.

Tawn is a self-hosted memory and context core that unifies your work, wealth, research, and academic life into one searchable brain — shared across every AI agent you use (Claude Code, Cursor, Gemini CLI, and others).

```
pip install tawn
tawn init
tawn web start    # opens the web dashboard at http://tawn:8787
```

## What it does

- **Memory federation** — indexes conversations from Claude, ChatGPT, Gemini, Obsidian, and local files into one semantic store
- **Domain modules** — Work, Wealth (read-only), Research, and Academic — each with its own compiled wiki and entity graph
- **Multi-provider model routing** — Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter, Ollama; local by default, cloud when needed
- **MCP server** — any MCP-compatible agent gets `recall`, `note`, and `brief` verbs against your twin's memory
- **Web dashboard** — streaming chat, memory browser, audit log, settings — at `tawn:8787`
- **Capability grants** — deny-all filesystem access by default; every read and write is audited

## Quick start

### Requirements

- Python 3.12+
- PostgreSQL (for memory and federation tables)
- Node.js 18+ (only needed if installing from source)

### Install

```bash
# fast core install (add providers when needed)
pipx install tawn

# or install everything at once
pipx install "tawn[full]"

# individual provider extras
pip install "tawn[anthropic]"   # Claude
pip install "tawn[openai]"      # OpenAI / OpenRouter
pip install "tawn[gemini]"      # Google Gemini
pip install "tawn[ollama]"      # local models
pip install "tawn[vectors]"     # pgvector for semantic search
pip install "tawn[mcp]"         # MCP server
```

### Setup

```bash
tawn init                  # creates ~/.tawn/
tawn db setup              # initialises PostgreSQL
tawn web start             # starts the web server at tawn:8787
```

Configure model providers:

```bash
tawn setup                 # interactive wizard — sets API keys, DB, local model
```

Or set keys directly:

```bash
# keys are stored in the OS keyring, never in files
tawn setup                 # interactive
```

### MCP integration (Claude Code)

Add to your `~/.claude/claude.json`:

```json
{
  "mcpServers": {
    "tawn": {
      "command": "tawn",
      "args": ["mcp"]
    }
  }
}
```

Then from any Claude session: `tawn.recall("…")`, `tawn.note("…")`, `tawn.brief("work")`.

## Domain modules

| Domain | What it tracks |
|--------|---------------|
| **work** | Tasks, projects, decisions — per employer |
| **wealth** | Portfolio, net worth, holdings — **read-only, never trades** |
| **research** | Papers, experiments, entity graph, morning brief |
| **academic** | Applications, deadlines, proposal drafts |

Extend with your own domain:

```bash
tawn domain add health     # scaffolds a new domain plugin
```

## CLI reference

```
tawn                       # chat with your twin
tawn note "…"              # append a note to today's raw file
tawn recall "query"        # semantic search over compiled memory
tawn brief work            # daily summary for a domain
tawn compile               # compile raw/ into wiki + vectors
tawn federation sources    # list federated AI tool sources
tawn federation merge      # ingest pending federation records
tawn web start/stop/status # web server control
tawn update                # check and install latest release
tawn config list           # view all settings
```

## Architecture

```
~/.tawn/
├── raw/          # immutable ingested sources
├── wiki/         # compiled markdown knowledge
├── federation/   # AI tool exports + adapters
├── grants.yaml   # capability grants (deny-all default)
└── audit.log     # every write, every cross-domain action
```

API server binds to `127.0.0.1` only. Wealth core is read-only. No withdrawal credentials ever stored.

## License

MIT — see [LICENSE](LICENSE).
