Metadata-Version: 2.4
Name: coretx
Version: 0.5.1
Summary: Structured memory for AI that persists, attributes, and connects
License-Expression: MIT
Requires-Python: >=3.9
Provides-Extra: remote
Requires-Dist: mcp[cli]>=1.9.0; extra == 'remote'
Provides-Extra: signing
Requires-Dist: cryptography>=41.0.0; extra == 'signing'
Description-Content-Type: text/markdown

# CoreTx Connect

Give your AI assistant persistent memory that survives across conversations, sessions, and devices. Discover complementary research across the CoreTx network.

CoreTx Connect is a lightweight MCP server that stores knowledge objects (KOs) via the CoreTx API. Your assistant captures decisions, facts, preferences, and insights as you work, and retrieves them automatically in future sessions. With the Research Network, you can discover complementary research from other scientists through anonymous, privacy-preserving matching.

**What changes**: Your AI remembers what you discussed last week. It recalls architectural decisions from three months ago. It knows your preferences without being told again. When context compaction would normally erase critical details, KOs preserve them. And when you opt in, it finds researchers whose work complements yours.

## Quick Start

### Claude Desktop (automatic setup)

```bash
# 1. Install
pip install coretx-connect

# 2. Run setup (writes Claude Desktop config automatically)
coretx-connect setup <your-api-key>

# 3. Restart Claude Desktop
```

### Claude Code (CLI)

```bash
# 1. Install
pip install coretx-connect

# 2. Add to Claude Code
claude mcp add --transport stdio ko-memory -- coretx-connect

# 3. Set your key (add to your shell profile for persistence)
export CORETX_API_KEY=npub_sk_xxx

# 4. Verify everything works
coretx-connect --test
```

The `--test` command checks API connectivity, writes and reads a test KO, and confirms your setup is working.

### Getting an API key

API keys are currently issued by your team lead. Ask them for a key that starts with `npub_sk_`.

> **Note:** Self-service key creation via nanopub.coretx.ai is not yet available. This will be enabled in a future update.

## How It Works

When you start a conversation, your assistant calls `ko_context` to load relevant knowledge from previous sessions. As you work, it proactively captures decisions, facts, and insights via `ko_write`. These KOs persist server-side and are available in every future session, on any device, with any AI provider.

```
You: "Let's use PostgreSQL on Supabase for the database"
  -> ko_write(subject='database', predicate='decided as', object_value='PostgreSQL on Supabase')

[Three weeks later, new session]

Assistant calls ko_context -> loads the database decision automatically
You: "What database are we using?"
  -> Already knows: PostgreSQL on Supabase
```

## Tools

### Cloud tools (persistent, require API key)

| Tool | What it does |
|------|-------------|
| `ko_write` | Store a knowledge object. Called proactively by the assistant. Supports `visibility` parameter. |
| `ko_read` | Retrieve a specific KO by subject + predicate. |
| `ko_search` | Search KOs by keyword or natural language. |
| `ko_list` | List recent KOs, optionally filtered by project. |
| `ko_delete` | Delete a KO by subject + predicate. |
| `ko_context` | Load session-start context (pinned + recent + relevant KOs). |
| `ko_stats` | Get store statistics (total KOs, projects, pinned count). |
| `ko_share` | Share KOs with another CoreTx user by email or ORCID. |

### Privacy and visibility tools

| Tool | What it does |
|------|-------------|
| `ko_set_visibility` | Change a KO's visibility: `private`, `matchable`, or `public`. |

### Research Network tools (require Network tier)

| Tool | What it does |
|------|-------------|
| `ko_discover` | Find complementary research from other researchers via anonymous structural matching. |
| `ko_connect` | Express interest in connecting with a match. Both parties must opt in before identities are revealed. |

### Local tools (session-scoped, no API key needed)

| Tool | What it does |
|------|-------------|
| `ko_set_context` | Set project/goal for smarter retrieval. |
| `ko_working_memory` | Ephemeral scratch memory (auto-expires after 1 hour). |
| `ko_todos` | Task tracking within the session. |

## Privacy Tiers

Every KO has a visibility level:

| Level | Who can see it | Matching | Content shared |
|-------|---------------|----------|----------------|
| `private` | Only you | No | No |
| `matchable` | Anonymous structural match only | Yes | No (properties only) |
| `public` | Anyone in the network | Yes | Yes |

Default is `private`. Set visibility when writing:

```
ko_write(subject='...', ..., visibility='matchable')
```

Or change it later:

```
ko_set_visibility(ko_id='abc123', visibility='public')
```

See [docs/product-tiers.md](docs/product-tiers.md) for the full privacy and account tier specification.

## Account Tiers

During beta, all users are on the **Network** tier (all features free).

| Feature | free | pro | network | institutional |
|---------|------|-----|---------|---------------|
| KO limit | 500 | 10,000 | unlimited | unlimited |
| private | Y | Y | Y | Y |
| matchable | - | - | Y | Y |
| public | - | Y | Y | Y |
| ko_discover | - | - | Y | Y |
| ko_connect | - | - | Y | Y |
| Cloud sync | - | Y | Y | Y |
| Team matching | - | - | - | Y |

Override the tier for testing: `export CORETX_TIER=free`

## CLI Commands

### Bootstrap (cold start from Claude Code history)

If you have existing Claude Code sessions, bootstrap your knowledge store from them:

```bash
coretx-connect bootstrap --dry-run    # preview what would be extracted
coretx-connect bootstrap              # extract and write KOs
coretx-connect bootstrap --path /custom/logs/path
```

This scans your Claude Code JSONL logs (`~/.claude/projects/`) and extracts decisions, facts, problems, and preferences as KOs. Projects are inferred from directory names.

### Reclassify (organize unassigned KOs)

If you have KOs without a project, classify them based on your existing project keywords:

```bash
coretx-connect reclassify --dry-run   # preview classifications
coretx-connect reclassify             # apply classifications
```

### Other commands

```bash
coretx-connect --test      # verify API connectivity
coretx-connect --version   # show version
coretx-connect setup <key> # configure Claude Desktop
```

## Environment Variables

| Variable | Required | Default |
|----------|----------|---------|
| `CORETX_API_KEY` | Yes (for cloud tools) | -- |
| `CORETX_API_URL` | No | `https://api.coretx.ai` |
| `CORETX_TIER` | No | `network` (all features, beta default) |

## Troubleshooting

**"CORETX_API_KEY not set"** -- Make sure your API key is set via the `setup` command or in your environment.

**Server not appearing in Claude Desktop** -- Restart Claude Desktop after running `setup`.

**"HTTP 401" errors** -- Your API key is invalid or expired. Ask your team lead for a new one.

**"requires the Network tier"** -- You are on a tier that does not include this feature. During beta, set `CORETX_TIER=network` to unlock all features.

**Wrong Python version** -- Re-run `coretx-connect setup <key>` -- it uses the correct Python automatically.

## Team Setup

Each team member needs their own API key. KOs are per-user and private by default. To share knowledge across the team, use `ko_share` with a colleague's email or ORCID. To discover complementary research, set some KOs to `matchable` and use `ko_discover`.

```bash
# Each team member runs:
pip install coretx-connect
claude mcp add --transport stdio ko-memory -- coretx-connect
export CORETX_API_KEY=npub_sk_xxx  # their own key
coretx-connect --test
```

## Architecture

- **Local server**: MCP over stdio for Claude Code / Desktop
- **Remote server**: Streamable HTTP for claude.ai browser (`coretx-connect-remote`)
- **Storage**: All persistent state at `api.coretx.ai` (no local database)
- **Auth**: Bearer token (`npub_sk_*` API keys), OAuth 2.1 for browser
- **Signing**: Ed25519 client-side signing (visibility included in signed payload)
- **Privacy**: Three-tier visibility (private/matchable/public), mutual opt-in for connections
- **Server name**: `ko-memory`
