Metadata-Version: 2.4
Name: hollow-attractor
Version: 0.2.5
Summary: Cross-session personal memory and task protocol for Claude
Project-URL: Homepage, https://github.com/wjdhollow/hollow-attractor
Project-URL: Repository, https://github.com/wjdhollow/hollow-attractor
Project-URL: Bug Tracker, https://github.com/wjdhollow/hollow-attractor/issues
Author: wjdhollow
License: MIT
Keywords: ai,claude,mcp,memory,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# Hollow Attractor

Cross-session personal memory and task protocol for Claude, implemented as an MCP server.

Claude has no memory between sessions. Hollow Attractor gives it a persistent, structured workspace — tracked in a local git repo, read and written through MCP tools, never sent anywhere.

---

## How it works

Hollow Attractor runs as a local MCP server connected to Claude Desktop. Each session, Claude loads your current state and picks up where it left off — open tasks, decisions, questions, and a running log.

Everything lives in `~/.hollow-attractor/` as plain text files under git. No cloud, no account, no sync. Your data stays on your machine.

### Key concepts

| Term | Meaning |
|------|---------|
| **Worldline** | A named workspace — one project, one scope |
| **Attractor** | The global context; entry point for each session |
| **Ship Log** | Global index of all worldlines and recent updates |
| **Divergence** | A tracked relationship between two worldlines |
| **Anneal** | Manual compaction of a worldline with optional intent |
| **Imprint** | Plain-text state export for backup or migration |

---

## Install

**Requirements:** Python 3.10+, git, [Claude Desktop](https://claude.ai/download)

```bash
pip install hollow-attractor
hollow init
```

Then configure the MCP server for your Claude client:

**Claude Desktop** — edit `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hollow-attractor": {
      "command": "hollow",
      "args": [],
      "env": {}
    }
  }
}
```

**Claude Code (CLI)** — edit `~/.claude.json`, using the full path to the `hollow` binary:

```json
{
  "mcpServers": {
    "hollow-attractor": {
      "type": "stdio",
      "command": "/full/path/to/hollow",
      "args": [],
      "env": {}
    }
  }
}
```

To find the full path: `which hollow` (macOS/Linux) or `where hollow` (Windows).

Restart Claude Desktop / Claude Code after saving.

---

## Usage

Start a session in Claude Desktop and say:

> *hollow, start*

Claude will load the `hollow_start` prompt, read your Ship Log, and resume your current worldline.

From there you can create worldlines, add tasks, log decisions, track open questions, and commit state — all through conversation.

See [`SYSTEM_PROMPT.md`](SYSTEM_PROMPT.md) for the full protocol and [`SCHEMAS.md`](SCHEMAS.md) for file formats.

---

## Migrating from an existing system

Already tracking tasks in Notion, Todoist, a custom Claude setup, or anywhere else? See [MIGRATION.md](MIGRATION.md) for a prompt you can paste into Claude Desktop to bring your existing backlog across.

---

## Status

V1 is complete and in active daily use. The core protocol is stable.

Planned next:
- Homebrew formula
- Hosted sync (V2)

---

## Support

If Hollow Attractor is useful to you, consider sponsoring development:

[![GitHub Sponsors](https://img.shields.io/github/sponsors/wjdhollow?style=flat&label=Sponsor)](https://github.com/sponsors/wjdhollow)

---

## License

MIT
