memocode 0.3.4

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
• Multi-layer memory system — Cross-session persistence with structured compression, on-demand recall, and forgetting curve
• Project management — Multiple projects with separate memory DBs and working directories
• Built-in tools — Shell execution, file read/write/edit, glob, grep, web fetch, memory search
• 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": 65536,
      "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)
/memory	Show core memory (user profile)
/memory set <key> <value>	Write a core memory entry
/memory del <key>	Delete a core memory entry
/memory pin <key>	Pin an entry (stability=999, never forgets)
!<command>	Run shell command directly (safety-checked)
@<path>	Attach file contents to your message

Memory System

Mcode maintains four memory layers that persist across sessions:

Layer	Scope	Contents	Updated
Core memory	Global (all projects)	User traits: communication style, autonomy preference	Every compression + session end
Project memory	Per-project	Decisions, architecture, progress, conventions	Every compression + session end
Recent memory	Per-project	Compressed summaries of past sessions	Session end; grows indefinitely
Session history	Per-project	Current session verbatim + older turns compressed	Each turn

How recall works:

• Recent session summaries are automatically injected into every turn (newest-first, 4k token cap)
• The LLM calls memory_search when it needs context from older sessions — it decides when and what to search
• Project memory and core memory are always present in the system prefix (prompt-cache eligible)

Compression: When the session context reaches 50% of context_window, old turns are replaced with a structured summary (topics, decisions, progress, pending, key context). Raw code and config values are excluded — only decisions and rationale are preserved.

Forgetting: Core memory entries decay over time (Ebbinghaus curve). Entries not reinforced by the judge gradually fade, preventing stale user traits from persisting indefinitely.

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)
memory_search	Search past session summaries for relevant context

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
│       ├── context_manager.py   # Session history, compression, injection
│       ├── compressor.py        # LLM-based structured summarization
│       └── memory/
│           ├── core_memory.py   # User traits (global, with forgetting)
│           ├── recent_memory.py # Cross-session summaries (per-project)
│           ├── consolidation.py # Periodic pattern extraction → core memory
│           └── forgetting.py    # Ebbinghaus decay for core memory
├── 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