Metadata-Version: 2.4
Name: ctxmemory
Version: 0.1.0
Summary: Persistent memory for AI coding agents
Author: Anas Nafees
License: MIT License
        
        Copyright (c) 2026 Anas Nafees
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/anasnafees/contextkit
Project-URL: LinkedIn, https://www.linkedin.com/in/anas-nafees/
Keywords: ai,agents,memory,context,claude,cursor,copilot,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: anthropic>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: click>=8.0.0
Dynamic: license-file

# ContextKit

> Persistent memory for AI coding agents. Stop re-explaining your codebase every session.

AI coding agents such as Claude Code, Codex, Cursor, and Copilot reset completely between sessions.
You lose time re-explaining architecture, conventions, forbidden patterns, and past bugs.
ContextKit gives your repo a shared, evolving project brain.

## How it works

1. `ctx init` sets up a `.ctx/` brain in your repo.
2. `ctx add` adds memories manually, or `ctx watch` extracts them automatically.
3. `ctx inject claude` generates a fresh agent instruction file.
4. Every new session starts with project-specific context.

## Install

```bash
pip install ctxmemory
```

## Quickstart

```bash
cd your-project
pip install ctxmemory
ctx init
ctx add "We use Zod for all validation. Never use Yup." --type pattern
ctx add "Never mutate state directly - always use the store actions." --type forbidden
ctx inject claude
```

## Commands

| Command | Description | Key options |
| --- | --- | --- |
| `ctx init` | Create `.ctx/`, markdown files, and the SQLite index | None |
| `ctx add <content>` | Add a memory manually | `--type`, `--tags` |
| `ctx list` | List stored memories | `--type`, `--tags`, `--limit` |
| `ctx remove <id>` | Remove a memory by partial id | None |
| `ctx inject <agent>` | Generate an agent-specific context file | `--task`, `--file`, `--force` |
| `ctx watch` | Extract memory candidates from recent activity | `--since` |
| `ctx status` | Show totals, recent memories, and generated files | None |
| `ctx search <query>` | Search memories by content and tags | `--limit` |
| `ctx export` | Export all memories as markdown or JSON | `--format`, `--output` |

## Supported agents

| Agent | File generated |
| --- | --- |
| Claude Code | `CLAUDE.md` |
| Codex | `AGENTS.md` |
| Cursor | `.cursor/rules` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| OpenCode | `AGENTS.md` |

## Project brain layout

```text
.ctx/
  brain.db
  decisions.md
  patterns.md
  forbidden.md
  bugs.md
  context.md
  .gitignore
```

The markdown files are the source of truth. The SQLite database is a fast index for lookup and relevance.

## Auto-extraction (`ctx watch`)

`ctx watch` uses the Anthropic API to review recent git activity, Claude session logs,
or a manual session summary and suggest memories to add to your project brain.

Set `ANTHROPIC_API_KEY` before using automatic extraction:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

ContextKit resolves configuration in this order:

1. `ANTHROPIC_API_KEY`
2. `.env` in the project root
3. `~/.contextkit/config.toml`

Example global config:

```toml
[anthropic]
api_key = "sk-ant-..."

[watch]
default_since_minutes = 60
auto_approve_threshold = 0.9

[inject]
max_memories = 20
```

## Typical workflow

```bash
pip install ctxmemory
ctx init
ctx add "We use FastAPI, not Flask. Never suggest Flask." --type forbidden --tags "framework"
ctx add "All API responses use APIResponse in core/response.py." --type pattern --tags "api,response"
ctx inject codex
ctx status
ctx search auth
ctx watch --since 480
```

## License

MIT

## Author

Built by **Anas Nafees**  
LinkedIn: [https://www.linkedin.com/in/anas-nafees/](https://www.linkedin.com/in/anas-nafees/)

## Package name note

The product name is **ContextKit**, but the PyPI distribution name is **`ctxmemory`**
because `contextkit` is already taken on PyPI. The installed CLI command remains:

```bash
ctx
```
