Metadata-Version: 2.4
Name: memocode
Version: 0.2.3
Summary: Personal AI coding agent with memory, tool execution, and safety controls
Author: AssassinCHN
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: certifi>=2024.0

# Mcode

Personal AI coding agent CLI with memory, tool execution, and safety controls.


## Features

- **Agentic tool-use loop** — Native function calling (OpenAI / Anthropic compatible), stuck detection, auto mode for fully autonomous task execution
- **Memory system** — Persistent conversation memory with consolidation, forgetting curve, and cross-session injection
- **Project management** — Multiple projects with separate memory DBs and working directories
- **Built-in tools** — Shell execution, file read/write/edit, glob, grep, web fetch
- **Safety layer** — Human mode (zone checks + confirmation prompts) / Auto mode (whitelist + work_dir hard boundaries) / Bypass mode (session-only, explicit confirmation required)
- **Extensible** — Drop Python files into `~/.mcode/tools/` for custom tools

## Requirements

- Python 3.11+
- API key for a supported model (MiniMax, Kimi, or any OpenAI-compatible endpoint)

## Installation

```bash
pip install memocode
```

Configure your model in `~/.mcode/agent.json` (created on first run):

```json
{
  "active_model": "minimax",
  "models": {
    "minimax": {
      "provider": "openai",
      "model": "MiniMax-M2.7",
      "base_url": "https://api.minimaxi.com/v1",
      "api_key_env": "MINIMAX_API_KEY",
      "context_window": 1000000,
      "extra_body": {"reasoning_split": true}
    }
  }
}
```

```bash
export MINIMAX_API_KEY=your_key_here
mcode
```

## Usage

```bash
mcode                      # Start (auto-resumes last project)
mcode --project myapp      # Start with a specific project
mcode --verbose            # Show full tracebacks on errors
```

## Slash Commands

| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/status` | Show current settings |
| `/quit` / `/exit` | Exit |
| `/end` | End session (save to memory) |
| | |
| `/btw <question>` | Quick one-shot question — no memory, no tools |
| `/template [example]` | Show auto-mode task prompt template |
| | |
| `/auto [on\|off]` | Toggle auto mode (no prompts, hard boundaries) |
| `/auto whitelist [list\|add\|remove\|reset]` | Manage auto mode command whitelist |
| `/safety [on\|off]` | Toggle safety bypass (DANGEROUS, session-only) |
| | |
| `/project list` | List all projects |
| `/project workdir [path]` | Set working directory |
| `/project rename [<old>] <new>` | Rename a project (defaults to current) |
| `/project delete <name>` | Delete a project (glob patterns supported) |
| | |
| `/model [name]` | Show or switch LLM model |
| `/tools` | List all loaded tools |
| `/history [N]` | Show audit log |
| `/undo` | Undo the last run — restore code and/or rewind conversation |
| `/rollback` | Restore a specific backed-up file (file only, for audit) |
| `/rewind [N]` | Rewind conversation to turn N (conversation only) |
| `/profile` | Show/edit core memory (user profile) |
| | |
| `!<command>` | Run shell command directly (safety-checked) |
| `@<path>` | Attach file contents to your message |

## Auto Mode

Auto mode runs the agent fully autonomously — no confirmation prompts, hard safety boundaries (whitelist-only shell commands, writes restricted to `work_dir`).

Enable with `/auto on`, then use `/template` for a recommended task prompt structure:

```
Task: <one-line goal>
Context: work_dir, language/framework, entry point
Acceptance criteria: 1) ... 2) ... 3) ...
Constraints: do NOT modify <files>
Verify by running: <test command>
```

## Safety Modes

| Mode | Behavior |
|------|----------|
| Human (default) | Prompts for risky operations; backs up files before destructive ops |
| Auto (`/auto on`) | No prompts; blocks non-whitelisted commands and writes outside `work_dir` |
| Bypass (`/safety off`) | Skips all checks; session-only; requires typing `yes` to enable |

## Built-in Tools

| Tool | Description |
|------|-------------|
| `shell_exec` | Run shell commands (streaming output) |
| `file_read` | Read file with pagination |
| `file_write` | Write / append to file |
| `file_edit` | Targeted string replacement in file |
| `glob` | Find files by pattern (`**/*.py`) |
| `grep` | Search file content by regex |
| `web_fetch` | Fetch a URL, returns readable text (HTML stripped) |

## Custom Tools

Drop a Python file in `~/.mcode/tools/`:

```python
from tools.registry import Tool, ToolSchema

def _my_tool(param: str) -> str:
    return f"result: {param}"

MY_TOOL = Tool(
    schema=ToolSchema(
        name="my_tool",
        description="Description shown to the model",
        parameters={
            "type": "object",
            "properties": {"param": {"type": "string"}},
            "required": ["param"],
        },
    ),
    fn=_my_tool,
)
```

## Project Structure

```
mcode/
├── run.py                  # CLI entry point
├── control/
│   ├── brain.py            # Agent loop, tool dispatch, safety
│   ├── llm.py              # LLM adapter (OpenAI / Anthropic)
│   ├── project_manager.py  # Project registry
│   ├── audit.py            # Audit log
│   └── chatmem/            # Memory system
├── tools/
│   ├── file.py             # file_read/write/edit, glob, grep
│   ├── shell.py            # shell_exec
│   ├── web.py              # web_fetch
│   └── registry.py         # Tool registry + loader
└── safety/
    ├── safety.py           # Zone checks, auto mode rules
    ├── backup.py           # File backup
    └── policy.py           # Persistent always-allow policies
```
