Metadata-Version: 2.4
Name: cortex-identity
Version: 1.6.0
Summary: Own your AI memory. Take it everywhere.
Author: Junebugg1214
License-Expression: MIT
Project-URL: Homepage, https://github.com/Junebugg1214/Cortex-AI
Project-URL: Repository, https://github.com/Junebugg1214/Cortex-AI
Project-URL: Issues, https://github.com/Junebugg1214/Cortex-AI/issues
Project-URL: Documentation, https://github.com/Junebugg1214/Cortex-AI/blob/main/docs/SELF_HOSTING.md
Project-URL: Changelog, https://github.com/Junebugg1214/Cortex-AI/blob/main/CHANGELOG.md
Keywords: ai-identity,knowledge-graph,chatgpt,claude,memory,portable
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: asgi
Requires-Dist: starlette>=0.37.0; extra == "asgi"
Requires-Dist: uvicorn>=0.30.0; extra == "asgi"
Provides-Extra: crypto
Requires-Dist: pynacl>=1.5.0; extra == "crypto"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.7.0; extra == "embeddings"
Provides-Extra: fast
Requires-Dist: numpy>=1.24.0; extra == "fast"
Provides-Extra: model
Requires-Dist: pydantic>=2.6; extra == "model"
Provides-Extra: server
Requires-Dist: pynacl>=1.5.0; extra == "server"
Provides-Extra: full
Requires-Dist: pynacl>=1.5.0; extra == "full"
Requires-Dist: numpy>=1.24.0; extra == "full"
Requires-Dist: starlette>=0.37.0; extra == "full"
Requires-Dist: uvicorn>=0.30.0; extra == "full"
Requires-Dist: sentence-transformers>=2.7.0; extra == "full"
Requires-Dist: pydantic>=2.6; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pynacl>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: starlette>=0.37.0; extra == "dev"
Requires-Dist: uvicorn>=0.30.0; extra == "dev"
Requires-Dist: pydantic>=2.6; extra == "dev"
Dynamic: license-file

# Cortex

**Git for AI memory. Local-first, MCP-native.**

Cortex is a local memory layer for AI agents. It gives you a user-owned graph on disk with Git-like commits, branches, merge, blame, and source-backed retraction — and an MCP server any agent can read from.

No Cortex cloud. No Cortex API key. Your agent keeps using its own LLM; Cortex is just where the memory lives. Optional model-based extraction uses your own provider key.

**Works with:** Claude Code · Cursor · Codex · Windsurf · Copilot · Gemini CLI · ChatGPT · Grok · **[OpenClaw](docs/OPENCLAW_QUICKSTART.md)** · **[Hermes](docs/HERMES_QUICKSTART.md)**

```bash
python3.11 -m pip install --upgrade "cortex-identity @ git+https://github.com/Junebugg1214/Cortex-AI.git@main"
cortex init
cortex mind remember self "We use TypeScript and Supabase"
cortex mind mount self --to codex --project . --task "product strategy"
```

Demos: [retraction](demos/retraction.mp4) · [portability](demos/portability.mp4) · [audience](demos/audience.mp4) (also available as [asciinema casts](demos/README_DEMOS.md))

![portability](demos/portability.svg)

---

Local-first. No Cortex cloud, no Cortex key. Integrate over MCP, local REST, or SDK. Model extraction is opt-in and uses your own provider key.

This README is intentionally implementation-aligned. Examples use supported commands and supported input formats on a fresh install.

## Install

The current Mind CLI (`cortex init`, `cortex mind ...`) is available from the
GitHub build. A plain `pip install cortex-identity` may install an older PyPI
wheel whose help output does not include `init` or `mind`.

```bash
python3.11 -m pip install --upgrade "cortex-identity @ git+https://github.com/Junebugg1214/Cortex-AI.git@main"
cortex --help   # should list init and mind
```

On Windows, if pip says the user Scripts directory is not on `PATH`, add it for
the current terminal before running `cortex`:

```bat
py -3.11 -m pip install --user --upgrade "cortex-identity @ git+https://github.com/Junebugg1214/Cortex-AI.git@main"
set "PATH=%APPDATA%\Python\Python311\Scripts;%PATH%"
cortex --help
```

For development from source:

```bash
git clone https://github.com/Junebugg1214/Cortex-AI.git
cd Cortex-AI
python3.11 -m pip install -e ".[dev]"
cortex --help
```

## Quickstart: create a local Mind and mount it into Codex

```bash
mkdir cortex-demo
cd cortex-demo
cortex init
cortex mind remember self "We use TypeScript and Supabase."
cortex mind compose self --to codex --task "product strategy"
cortex mind mount self --to codex --project . --task "product strategy"
```

`cortex mind mount` writes a Cortex-managed block into `AGENTS.md` while preserving content outside the Cortex markers.

Use `cortex mount watch` when you have a graph file you want to keep mounted after changes. An example appears in the extraction section below.

## Extraction

Create a supported source file:

```bash
cat > policy_v3.md <<'EOF_POLICY'
# Policy v3
Data retention is 90 days.
We use Python, TypeScript, and Supabase.
Please keep compliance summaries concise.
EOF_POLICY
```

Extract it into a Cortex graph:

```bash
cortex extract run policy_v3.md --output policy_v3.context.json
cortex mount watch --project . --graph policy_v3.context.json --interval 30 --to codex
```

Default extraction is local and rule-based. Model and hybrid extraction are
available when configured, and all current backends use the typed extraction
contract described in [docs/EXTRACTION.md](docs/EXTRACTION.md).

Model extraction is opt-in:

```bash
export CORTEX_HOT_PATH_BACKEND=model
export CORTEX_ANTHROPIC_API_KEY=sk-ant-...
cortex extract run policy_v3.md --output policy_v3.context.json
```

PDFs require pre-conversion to a supported text or JSON format before ingest. See
[docs/INGEST_FORMATS.md](docs/INGEST_FORMATS.md) for the exact loader catalog,
and [docs/EXTRACTION.md](docs/EXTRACTION.md) for pipeline stages, diagnostics,
replay, evals, and the cost-aware router.

## Versioning workflow

```bash
cortex commit policy_v3.context.json -m "Initial policy memory"
cortex log --limit 5
cortex branch policy-review --switch
cortex commit policy_v3.context.json -m "Review policy context"
cortex branch switch main
cortex merge policy-review --dry-run
```

Cortex stores graph snapshots with refs and branch pointers under `.cortex/`. Recent versions use a Merkle-chained version id that folds ancestry metadata into the commit digest while leaving the graph hash as the content hash.

## Retraction and provenance

Cortex can retract source-backed graph content when nodes and edges carry provenance. The current safe workflow is to inspect source lineage first, then retract with a dry run:

```bash
cortex source list --mind self
```

After `cortex source list` shows a real source id, use `cortex source retract <source-id> --mind self --dry-run` before confirming a retraction. Extraction and merge paths attach provenance for generated nodes so retraction has lineage to follow.

## Portability

Cortex can write target-specific context files and artifacts. Round-trip pull support is narrower than write support.

| Target | Write / mount | Round-trip (pull) |
| --- | --- | --- |
| Claude | ✅ | ✅ |
| Notion | ✅ | ✅ |
| SystemPrompt | ✅ | ✅ |
| Claude Code | ✅ | ⚠ write-only |
| Codex | ✅ | ⚠ write-only |
| Cursor | ✅ | ⚠ write-only |
| Copilot | ✅ | ⚠ write-only |
| Windsurf | ✅ | ⚠ write-only |
| Gemini CLI | ✅ | ⚠ write-only |
| ChatGPT export artifacts | ✅ | ⚠ write-only |
| Grok export artifacts | ✅ | ⚠ write-only |
| Hermes runtime context | ✅ | ⚠ write-only |

Examples:

```bash
cortex sync policy_v3.context.json --to codex --project .
cortex mount watch --project . --graph policy_v3.context.json --to codex cursor
cortex source status --project .
cortex status --project .
```

`cortex sync` and `cortex mount watch` preserve user content outside Cortex marker blocks when writing instruction files.

## Deduplication

Deduplication today uses lexical label similarity plus graph-neighbor overlap. It does not use embeddings. Duplicate candidates are compacted transitively, so if A matches B and B matches C above threshold, all three can collapse into one canonical node even when A and C are below threshold directly.

## Remotes and federation

Remotes today are local-filesystem paths only. Network transport is on the roadmap.

Federation bundles are signed graph exports for cross-instance sharing. Signature verification reports structured failures for malformed bundles, untrusted keys, and invalid signatures.

## Agent runtime

The agent runtime commands are available under the admin namespace:

`$ cortex admin agent monitor --interval 300`

`$ cortex admin agent compile --mind personal --output cv`

`$ cortex admin agent status`

## MCP and local service surfaces

```bash
cortex serve mcp --help
cortex serve --help
cortex admin openapi --help
```

The HTTP server is intended for local or operator-managed deployments. Put it behind a real TLS/auth/rate-limit boundary before exposing it beyond localhost.

## Core commands

| Command | Purpose |
| --- | --- |
| `cortex init` | Initialize `.cortex` and the default Mind |
| `cortex mind remember` | Add a fact or preference to a Mind |
| `cortex mind compose` | Preview a target-specific runtime slice |
| `cortex mind mount` | Write a Mind slice into supported local tool files |
| `cortex mount watch` | Poll a graph and refresh mounted context files |
| `cortex extract run` | Convert supported input files into a Cortex graph |
| `cortex sync` | Propagate context across configured targets |
| `cortex compose` | Render context without writing a persistent mount |
| `cortex commit` | Save a graph snapshot to the version store |
| `cortex branch` | Create or list memory branches |
| `cortex branch switch` | Switch active branch |
| `cortex merge` | Merge another memory branch |
| `cortex diff` | Compare two versions |
| `cortex debug review` | Review a graph or branch before merge |
| `cortex source` | Inspect and retract source lineage from Minds |
| `cortex pack` | Manage Brainpacks |
| `cortex audience` | Manage audience disclosure policies |
| `cortex remote` | Push/pull local-filesystem remotes |
| `cortex verify` | Verify signed exports |
| `cortex admin integrity check` | Verify store lineage, version chains, and checksums |
| `cortex admin doctor` | Inspect and repair local store/config issues |

Run `cortex COMMAND --help` for the exact flags supported by your installed version.

## Development

```bash
git clone https://github.com/Junebugg1214/Cortex-AI.git
cd Cortex-AI
python3.11 -m pip install -e ".[dev]"
ruff check cortex tests
python3.11 -m pytest tests -q --tb=short
```

## Status

Cortex is production-fit for disciplined local-first and small-team self-hosted workflows. It is not a hosted memory cloud, not a cloud multi-tenant service, and not a default LLM extractor. The strongest current core is versioned graph storage, branch/merge/review, source-backed retraction, local tool mounts, audience filtering, and MCP/local service integration.

## License

MIT. See [LICENSE](LICENSE).
