Metadata-Version: 2.5
Name: cyclegen
Version: 0.1.2
Summary: CycleGen — 3次元記憶システム（スキル・記憶ストア）を備えた人間-AI協働フレームワーク
Project-URL: Homepage, https://cyclegen.ai
Project-URL: Repository, https://github.com/cyclegen/core
Project-URL: Changelog, https://github.com/cyclegen/core/blob/main/CHANGELOG.md
License: Apache-2.0
License-File: LICENSE
Keywords: ai,context-engineering,cyclegen,knowledge-management,mcp,memory
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.25
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: docx
Requires-Dist: python-docx>=1.0.0; extra == 'docx'
Provides-Extra: semantic
Requires-Dist: fastembed<0.9,>=0.4; extra == 'semantic'
Requires-Dist: numpy>=1.24; extra == 'semantic'
Description-Content-Type: text/markdown

# CycleGen Core

**A human–AI collaboration framework with a 3-dimensional memory store (Skill & Memory Store), built on the "Deep Out" design philosophy.**

CycleGen turns AI collaboration into a repeatable one-hour cycle: the AI works autonomously, you review and decide, and the context you accumulate is structured and re-injected — so the same model gets qualitatively better at *your* work over time. CycleGen Core is the open-source (Apache-2.0) personal edition.

> "Rent the model. Own the context."

日本語版は [README.ja.md](./README.ja.md) を参照してください。

---

## What's inside

CycleGen Core ships an **MCP server** exposing **19 tools** for a semantic, self-ranking memory store:

- **Semantic memory search** — recall the right memories by meaning, following Miller's 7±2 so a search returns a set you can actually hold in your head.
- **Store / update / pin / archive** — capture knowledge as you work. Every memory is filed on 3 axes (Layer / Priority / Context), and **priority rises with use** — memories you rely on surface more readily, and ones that miss can be pushed down explicitly.
- **Cycle lifecycle** — `cycle_complete` records a work cycle and surfaces promotion candidates.
- **CycleGen Finish** (optional `docx` extra) — convert Markdown to styled `.docx`.

## Install

CycleGen Core runs as an MCP server. The recommended way is via [`uv`](https://docs.astral.sh/uv/):

```bash
# Run the MCP server directly (installs on first use)
uvx --from "cyclegen[semantic,docx]" cyclegen-mcp
```

Or with pip:

```bash
pip install "cyclegen[semantic,docx]"
cyclegen-mcp
```

- `semantic` — embeddings backend for memory search (recommended; first run downloads a small model).
- `docx` — enables the `document_finish` / `list_finish_templates` tools.

### Prerequisite: install uv (one line per OS)

The MCP server is launched through `uvx`, so **install uv first**:

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
# Windows (PowerShell)
winget install --id=astral-sh.uv -e
```

You do not need to install Python yourself — uv provides the right version and puts it on your PATH.
On Windows, **open a new terminal window** before checking `uv --version`.

> **Why not `irm ... | iex` on Windows?**
> The one-liner published on uv's own site is rejected by the default execution policy
> (`Restricted`) on a clean Windows 11 install:
> `Error: PowerShell requires an execution policy in [Unrestricted, RemoteSigned, Bypass] to run uv.`
> Working around it means loosening an OS security setting with `Set-ExecutionPolicy` — and on a
> company-managed machine that is often locked by group policy, so it may not be possible at all.
> `winget` asks you to press `Y` once and changes no settings. It also resolves
> `Microsoft.VCRedist.2015+.x64` as a dependency, which the `irm | iex` path does not.

### Claude Code — use as a plugin (recommended)

CycleGen ships a plugin that wires the MCP server **and** the cycle discipline (hooks, skills, the approval-gate protocol) automatically — no manual MCP configuration, no cloning this repository.

**In the desktop app, install it from the screen** — the Code tab does not accept `/plugin`:

```
1. Click the [+] next to the prompt box → "Add plugins"
2. A screen titled "Directory" opens, with "Plugins" selected on the left.
   Click the [＋] at its top right
3. Under "Add from repository", enter  cyclegen/core
4. Click the [＋] at the top right of the "Cyclegen core" panel to install it
```

> **Three `[＋]` buttons appear in a row, and they are in three different places** — (1) next to the
> prompt box, (2) at the top right of the screen, (3) at the top right of the panel. **They are not
> the same button.**

**How you know it worked**: the `[＋]` on the panel turns into a **gear icon**. No version number is
shown anywhere on that screen, so **this is the only signal that the install succeeded.**

**If you use the `claude` terminal**, these commands work instead:

```
/plugin marketplace add cyclegen/core
/plugin install cyclegen-core@cyclegen
```

Then restart the app so the MCP server is picked up — **nothing appears until you do**, even though
the install reports success.

### Codex — wire it with the bundled command

Codex has no plugin mechanism, so the package ships a setup command instead. No cloning here either.

```bash
# See what would be written first
uvx --from "cyclegen[semantic,docx]" cyclegen setup codex --dry-run

# Wire it
uvx --from "cyclegen[semantic,docx]" cyclegen setup codex
```

This writes `~/.codex/config.toml` (MCP), `~/.codex/hooks.json` (the discipline hooks) and `~/.agents/skills/` (seven skills). Restart Codex afterwards.

- Existing settings are never rewritten in place; backups (`*.cyclegen-bak`) are kept, and running it twice is safe.
- To undo: `cyclegen setup codex --remove`. **Your stored memories are left untouched.**

- Plugin details and what gets wired: [plugins/cyclegen-core/README.md](./plugins/cyclegen-core/README.md)
- Wiring Codex by hand: [plugins/cyclegen-core/manifests/codex/README.md](./plugins/cyclegen-core/manifests/codex/README.md)

## Updating to a newer release

### Claude Code

#### 1. Turn auto-update on first (once, on the day you install)

> **Third-party marketplaces have auto-update off by default.** The official wording is: "official
> Anthropic marketplaces default to true and **all other marketplaces default to false**". CycleGen is
> one of those, so **updates will not reach you unless you turn this on yourself.**

Open `~/.claude/settings.json` and add one line to `cyclegen` — **inside `extraKnownMarketplaces`**:

```jsonc
{
  "extraKnownMarketplaces": {
    "cyclegen": {
      "source": { "source": "git", "url": "https://github.com/cyclegen/core.git" },
      "autoUpdate": true
    }
  }
}
```

**`cyclegen` is not at the top level — it lives inside `extraKnownMarketplaces`.**
**Put `"autoUpdate"` next to `source`, not inside it.** Leave the other keys (`enabledPlugins` and so on)
exactly as they are.

Without it, the update entry point itself may never appear — the "Update" button seems to show up when
the marketplace has been refreshed, not when an update exists.

#### 2. Updating by hand

```
the [+] button next to the prompt box → Plugins → Cyclegen core → "Update" (top right)
```

> **There is no "Update" in the settings screen** (Settings → Plugins), neither in the list nor in the
> detail view. A different entry point opens a different screen; the one the official docs point at is
> `[+]`.
>
> With the **`claude` terminal** you can also run `/plugin update cyclegen-core` — but note that
> **if you only use the desktop app, the `claude` command is not installed.**

Once an update does go through, `.mcp.json` is replaced along with everything else, so **the MCP
server moves to the new version too**.

To check which version is actually wired:

```powershell
# Windows
Get-ChildItem -Recurse -Filter ".mcp.json" $env:USERPROFILE\.claude\plugins |
  Select-String -Pattern "cyclegen\[semantic"
```

```bash
# macOS / Linux
grep -r 'cyclegen\[semantic' ~/.claude/plugins --include=.mcp.json
```

### Codex — **pass `--force`**

```bash
uvx --from "cyclegen[semantic,docx]" cyclegen setup codex --force
```

> **Without `--force` you get a half-upgrade.**
> `setup codex` compares versions for the payload (skills and hooks) but **not** for
> `~/.codex/config.toml`: if a `[mcp_servers.cyclegen]` block is already there, it is left alone.
>
> | | |
> |---|---|
> | Skills and hooks | **updated** |
> | The version pin in `config.toml` | **left at the old version** |
>
> The output looks like a success — ticks all the way down, no warning — but the MCP server that
> actually runs is still the old one, so **new skills end up calling tools the running server does
> not have**.
>
> With `--force`, `config.toml` is replaced as well (your previous file is kept as `*.cyclegen-bak`).

To check which version is actually wired:

```bash
grep 'cyclegen\[semantic' ~/.codex/config.toml
```

### After updating — **quit the app completely, then start it again** (both Claude Code and Codex)

> **Closing the window is not enough.** The process can stay alive, and then your settings are never
> re-read.
>
> The symptom is that **the memory tools are missing after an update** (`memory_*` and
> `cycle_complete` are not in the tool list). It looks like the update broke something. It did not.
>
> **The fix is to quit properly and start again** — ten seconds if you know, unrecoverable if you
> don't.

The same shape shows up right after installing, too: the success message appears, but nothing is there
until you restart. "Restart" simply means something different to you and to the app.

## MCP client configuration (manual)

```json
{
  "mcpServers": {
    "cyclegen": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "cyclegen[semantic,docx]", "cyclegen-mcp"]
    }
  }
}
```

## Documentation

- Plugin (Claude Code / Codex): [plugins/cyclegen-core/README.md](./plugins/cyclegen-core/README.md)
- Changelog: [CHANGELOG.md](./CHANGELOG.md)
- Website & guides: **https://cyclegen.ai** ([what CycleGen is](https://cyclegen.ai/about/) / [FAQ](https://cyclegen.ai/faq/) / [materials](https://cyclegen.ai/resources/))

## License

Apache License 2.0 — see [LICENSE](./LICENSE). Copyright 2026 rashiku Corp.
