memocode 0.3.0

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

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

pip install memocode

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

{
  "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}
    }
  }
}

export MINIMAX_API_KEY=your_key_here
mcode

Usage

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/:

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