Metadata-Version: 2.4
Name: context-llemur
Version: 0.2.0
Summary: context-llemur: collaborative memory for humans and LLMs
Author: jerpint
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: fastmcp>=2.10.2
Requires-Dist: gitpython>=3.1.0
Requires-Dist: tomli_w>=1.0.0
Dynamic: license-file

# context-llemur 🐒

*Stop re-explaining your context to every LLM.*

Every AI conversation starts from zero. Whether you're switching from Claude to Cursor, or from ChatGPT to a local LLM, you're constantly re-explaining your project context. `ctx` solves this by giving you **portable, version-controlled context** that travels between ALL your AI tools.

## **ctx Features**

- **🔄 MCP Server Integration**: Full Model Context Protocol support
- **📦 Portable Context**: Same context works in Claude, Cursor, ChatGPT, and local LLMs  
- **🌲 Branching Conversations**: Explore alternatives without losing your main thread
- **🔧 Git-Based**: It's just git under the hood - no magic, no vendor lock-in, no assumptions

## ctx Workflow

```bash
# Create new project
ctx new "my-awesome-project"

# Morning: Curate your ideas with e.g. Claude Desktop via MCP
# Just start the conversation with "ctx load"
ctx load 

# ... work with Claude on model design ...
ctx save "Decided on PostgreSQL with Redis cache"
# ... Or just ask Claude to save for you!

# Afternoon: Cursor builds on Claude's work
# Cursor now knows about your database decisions
# Just prompt with e.g. "implement next steps"
ctx load

# Evening: Explore new ideas without affecting the main context with another LLM
ctx explore "serverless-alternative"
# ... explore serverless approach ...
ctx save "Serverless could work but cost concerns"

# When ready, re-integrate the ideas back to main context
ctx integrate

# Next day: Any AI tool knows your full journey
ctx load
```

## Installation

For now, install with uv:
```bash
uv add context-llemur
```

After installation, activate your environment to use the `ctx` command directly:
```bash
source .venv/bin/activate
ctx --help
```

Alternatively, you can use `uv run ctx ...`
Or with pip:
```bash
pip install context-llemur
```


## Quickstart

Start by initializing a new `ctx` folder: 

    ctx new

This will create, in your current directory, a new `context` folder and a `ctx.config` file to keep track of multiple context folders.

```bash
# Create a new context/ repository
ctx new

# add/edit some files inside the `context/` directory
echo "The next goal of this project is to..." >> context/goals.txt

# Save your context over time
ctx save "Updated goals"  # equivalent to git add -A && git commit -m "..."
```

## MCP Server Integration

`ctx` includes a full MCP server with tools that give AI agents persistent, version-controlled memory.

### Starting the MCP Server

```bash
ctx mcp
```

### Claude Desktop Integration

Add this to your `~/Library/Application\ Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "context-llemur": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/contexts/",
        "--with",
        "context-llemur",
        "ctx",
        "mcp"
      ]
    }
  }
}
```

Now start your conversation with `ctx load` and your AI agent will have access to:
- **Repository Management**: Create, switch, and manage contexts
- **Semantic Workflows**: Explore topics, save insights, integrate knowledge
- **File Operations**: Read, write, and organize context files
- **Navigation**: Browse branches, history, and search content

## Core Commands

### Repository Management
- `ctx new [name]` - Create new context repository (default: ./context/)
- `ctx status` - Show current repository status
- `ctx list` - List all discovered context repositories
- `ctx switch <name>` - Switch to a different context repository

### Semantic Workflows
- `ctx explore <topic>` - Start exploring a new topic (creates a new branch)
- `ctx save <message>` - Save current insights, equivalent to `git add -A && git commit -m`
- `ctx integrate <exploration>` - Merge insights back to main context
- `ctx diff` - Show current changes
- `ctx discard [--force]` - Reset to last commit, dropping all changes

### File Operations
- `ctx mv <source> <destination>` - Move or rename files (git mv equivalent)
- `ctx rm <filepath> [--force]` - Remove files from repository (git rm equivalent)

### Content Operations
- `ctx show_all [directory]` - Display all file contents with clear delimiters
- `ctx recent` - Show recent activity and modified files
- `ctx mcp` - Start MCP server for AI agent integration

## Core Philosophy

- **Context is not code** The context of a project evolves naturally over time - goals, TODOs, rules, milestones, etc. These concepts are traditionally tracked outside of repos (think of PRs, Issues, etc.) - `ctx` tracks them as individual git repositories.
- **Context should be portable** You should be able to provide the context easily to any LLM or human, without any friction. Context should be as platform agnostic as possible.
- **Context history matters** - Just like code, it should be easy to track what changed in context, revert to previous states and freely explore without fear of losing context
- **Each context is different** As little assumptions as possible should have to be made about the structure and contents of context

## Design
An important design decision of `ctx` is to *not* use embeddings. The idea is that context windows are getting longer, and agents are getting more capable of finding information when properly structured.

At its core, a `ctx` folder is an independently tracked `git` repository. It can easily be loaded as an MCP server, and exposes all `ctx` primitives by default to any LLM with its own `ctx.txt` file.

## Managing Contexts

`ctx` supports switching between multiple independent contexts. 

Creating a new context will automatically switch to the new context. Switch back to the previous context using `ctx switch`.

Contexts are managed using the following two files:

- **`.ctx.config`**: TOML file at the root of the project which tracks active and available repositories
- **`.ctx` marker**: Empty file in each context repository for identification

Example `.ctx.config`:
```toml
active_ctx = "research"
discovered_ctx = ["context", "research", "experiments"]
```

This design allows you to:
- Create multiple context repositories in the same workspace
- Switch between them easily with `ctx switch <name>`
- Work from your project root without changing directories
- Keep repositories portable and git-friendly

## Advanced Workflows

You can `explore` new ideas and `integrate` them back to the main context when ready:

```bash
ctx explore "new-feature"
echo "the first feature we will work on will be..." > TODOS.txt
ctx save "add new feature"
ctx integrate "new-feature"
```

`ctx` is mostly wrapper commands around a git repository, so if you navigate to your `ctx` repository, you can also just use whatever git commands you are used to.


## Git Command Mapping
For users familiar with git, here's the direct mapping:

| ctx Command | Git Equivalent | Purpose |
|-------------|----------------|---------|
| `ctx explore <topic>` | `git checkout -b <topic>` | Create and switch to new branch |
| `ctx save "<message>"` | `git add -A && git commit -m "<message>"` | Stage and commit changes |
| `ctx integrate <branch>` | `git merge <branch>` | Merge branch into current |
| `ctx status` | `git status && git branch` | Show repo and branch status |
| `ctx discard` | `git reset --hard HEAD` | Reset to last commit |
| `ctx mv <source> <destination>` | `git mv <source> <destination>` | Move or rename files |
| `ctx rm <filepath>` | `git rm <filepath>` | Remove files from repository |

## Use Cases

### Cursor/Agentic IDEs/CLI tools

The primary use-case for `ctx` is for it to be used with agentic LLMs. In fact, `ctx` was developed using `ctx` and `cursor`!

A suggested workflow is to include the entire `context` folder at the start of each conversation. This can be done by adding e.g. a `.cursorrule` to always include the `context/` folder or by using the `MCP` server and the `ctx load` function.

By default, each new context folder includes the [ctx.txt](./src/template/ctx.txt) file, which explains to the LLM what context is, so it out-of-the-box will be aware that it is using `ctx` and know how to interact with it. `MCP` servers are also self-documenting so the LLM will immediately know what it can do with `ctx`.

---

⚠️ `ctx` is in active development and things might change.
