Metadata-Version: 2.4
Name: coretx
Version: 0.9.4
Summary: Structured memory for AI that persists, attributes, and connects
Project-URL: Homepage, https://coretx.ai
Project-URL: Documentation, https://github.com/coretxinc/coretx-connect#readme
Project-URL: Repository, https://github.com/coretxinc/coretx-connect
Project-URL: Issues, https://github.com/coretxinc/coretx-connect/issues
Project-URL: Dashboard, https://sapience.coretx.ai
Author-email: CoreTx <feedback@coretx.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,coretx,knowledge-graph,mcp,memory,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: cryptography<47.0.0,>=41.0.0
Provides-Extra: remote
Requires-Dist: mcp[cli]<2.0.0,>=1.9.0; extra == 'remote'
Description-Content-Type: text/markdown

# CoreTx Connect

Give your AI assistant persistent memory that survives across conversations, sessions, and devices.

CoreTx Connect is a lightweight MCP server (~450 lines, zero dependencies) 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.

**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.

## Quick Start

### Claude Desktop (automatic setup)

```bash
# 1. Install
pip install coretx

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

# 3. Restart Claude Desktop
```

### Claude Code (CLI)

```bash
# 1. Install
pip install coretx

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

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

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

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

### Getting an API key

You can create your own API key at [sapience.coretx.ai](https://sapience.coretx.ai) under API Keys, or use `coretx init` to create an account and key from the terminal.

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

### 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. |

## CLI Commands

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

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

```bash
coretx bootstrap --dry-run    # preview what would be extracted
coretx bootstrap              # extract and write KOs
coretx 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 reclassify --dry-run   # preview classifications
coretx reclassify             # apply classifications
```

### Other commands

```bash
coretx --test      # verify API connectivity
coretx --version   # show version
coretx 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_AUTOSEED` | No | `1` — set to `0` to disable the session-start project snapshot |
| `CORETX_INIT_CONTEXT` | No | `1` — set to `0` to disable the MCP-initialize memory preamble |

### Warm session startup

Two layers work together so sessions open with context automatically, without the assistant needing to call any ko-memory tool:

1. **MCP initialize preamble** — when your MCP client starts the server, the `initialize` response carries your pinned + recent semantic KOs across all projects, embedded directly in the protocol's `instructions` field. The assistant reads this as part of session setup. Controlled by `CORETX_INIT_CONTEXT`.

2. **First-tool-call project snapshot** — once a project is resolvable (from `ko_set_context` or the basename of `cwd`), the server prepends a project-scoped block of pinned KOs, open problems, and recent decisions to that tool's result. Fires at most once per session. Controlled by `CORETX_AUTOSEED`.

Both are best-effort: on timeout, API error, or when `CORETX_API_KEY` is unset, the server falls back to static instructions and the session still starts cleanly.

**Pinned is protected from truncation.** Each preamble is capped at ~8KB, but the Pinned section is always included in full — even if it alone overruns the budget. Only non-pinned sections (semantic / recent) get trimmed when context is large. This matches the user contract: pinning a KO means "always surface this."

### Capture control (privacy)

Knowledge capture is **paused by default** at session start and hard-enforced at the server layer: any `ko_write` attempt while paused is rejected without touching the network, regardless of what the model tries to do.

- **Code mode** — as soon as `ko_set_context` yields a resolvable project (from explicit `project` or `cwd` basename), capture auto-enables. Users running Claude Code in a project directory notice no change in behavior.
- **Chat mode** — without a project, capture stays paused. The model is instructed to tell users "memory capture is off for this session" and call `ko_resume` only when the user explicitly asks to enable it.
- **Explicit pause/resume locks the state.** Once a user calls `ko_pause` or `ko_resume`, later `ko_set_context` calls don't silently flip it. This is the privacy-critical invariant: the user's choice wins.

Three tools manage this:

| Tool | Use |
|---|---|
| `ko_pause` | Block all writes for this session. Optional `reason` surfaced on status checks. Use when the user describes a sensitive topic (medical, legal, financial, family, therapy) or explicitly asks not to be remembered. |
| `ko_resume` | Re-enable writes. Use when the user confirms they want persistent memory in a Chat session, or after a pause. |
| `ko_status` | Report the current state (paused/active, default/explicit, project context). |

## 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. Regenerate one at [sapience.coretx.ai](https://sapience.coretx.ai) under API Keys.

**Wrong Python version** — Re-run `coretx 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.

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

## Architecture

- **Local server**: MCP over stdio for Claude Code / Desktop
- **Remote server**: Streamable HTTP for claude.ai browser (`coretx-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 (local server only)
- **Server name**: `ko-memory`
