---
Note:️ This file provides global context and should ideally not be modified or removed
---

# context-llemur 🐒: Collaborative Memory for Humans and LLMs

context-llemur, or `ctx`, is a context-engineering CLI tool to enable collaborative memory for humans and LLMs - think "git for ideas".

`ctx` helps overcome LLM amnesia and aims to minimize human repetition by tracking the context of a given project using simple commands.

## What is ctx?
`ctx` is a version-controlled collaborative thinking system where ideas evolve through commits, branch into experiments, and merge across different minds (human and AI). 

Not a knowledge base, but a living memory that travels between LLM sessions.

## Key Problems We Solve
- **LLM Amnesia**: Every new session starts from zero
- **Lost Context**: Valuable conversations vanish when the window closes  
- **Linear Thinking**: Can't branch conversations or explore alternatives
- **Fragmented Memory**: Context scattered across different tools

## Core Commands

### Repository Management
```bash
ctx new                     # Create new ctx repository in 'context' directory
ctx new <directory>         # Create new ctx repository in custom directory  
ctx status                  # Show current branch and repository status
ctx list                    # List all discovered ctx repositories with status
ctx switch <name>           # Switch to a different ctx repository
```

### Exploration & Integration
```bash
ctx explore <topic>         # Start exploring a new topic or idea
ctx save "<message>"        # Save current insights (git add -A && git commit -m)
ctx integrate <exploration> # Merge insights back to main context
ctx discard                 # Reset to last commit, dropping all changes
ctx discard --force         # Reset and remove untracked files
```

## Quickstart Workflow

```bash
# Create a new context repository
ctx new # Creates ./context/ directory

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

# Save your context over time
ctx save "updated goals"  

# Explore new ideas and integrate them back
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"
```

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

## Why context-llemur?

- **Platform agnostic** - Doesn't adhere to a specific provider, e.g. `CLAUDE.md` or `cursorrules`
- **Portable**: Context repositories are just git directories with files, take them anywhere
- **Git-friendly**: Uses familiar git workflows under the hood, easy to add/extend commands
- **Flexible**: You control the workflow with the LLMs

## Managing Multiple Contexts

`ctx` supports switching between multiple independent contexts using:

- **`ctx.config`**: TOML file at the root tracking 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 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

## Best Practices

### Repository Structure
- Each ctx repository is identified by a `.ctx` marker file
- Multiple ctx repositories can coexist in the same workspace
- Commands work from any subdirectory within a ctx repository

### Branch Naming
- Use descriptive names: `bias-detection-approach`, `performance-optimization`
- Separate words with hyphens for readability

### Commit Strategy  
- Commit early and often to preserve thinking evolution
- Use clear commit messages that capture the insight or decision

### Integration Protocol
- Always preview integrations first with `--preview` flag when available
- Main branch represents the current consensus/truth
- Exploration branches are for trying new ideas and approaches

## Technical Notes
- ctx repositories are standard git repositories with additional tooling
- All git commands work normally within the ctx repository directory
- Files are stored as plain text for maximum compatibility
- Repository state travels with the ctx directory