From bccca1498d4599c43bb8785e47b8871a614b42a1 Mon Sep 17 00:00:00 2001 From: Kien Bui Date: Tue, 14 Apr 2026 06:16:59 +0000 Subject: [PATCH] release: v1.7.0 - Memory v2 (categories, dream cleanup, self-skeptical) - System prompt hardened (30/30 tools, security, negative rules) - Security CI (audit, deny, dependency review) - Browser, debug mode, GitHub integration, profiles, pinning - tree-sitter, arboard, auto-skill, FTS search - UX: spinner, bell, help categories, quit confirm, Ctrl+R - 274 tests, 30 tools, 51 PRs --- CHANGELOG.md | 48 +++++++++++++++++ README.md | 2 +- mc/Cargo.lock | 12 ++--- mc/Cargo.toml | 2 +- mc/docs/guides/getting-started.md | 66 +++++++++++++++++++++++ mc/docs/guides/memory.md | 90 +++++++++++++++++++++++++++++++ mc/docs/reference/config.md | 68 +++++++++++++++++++++++ mc/docs/reference/tools.md | 58 ++++++++++++++++++++ 8 files changed, 338 insertions(+), 8 deletions(-) create mode 100644 mc/docs/guides/getting-started.md create mode 100644 mc/docs/guides/memory.md create mode 100644 mc/docs/reference/config.md create mode 100644 mc/docs/reference/tools.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ba7025..6b4d673 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,53 @@ # Changelog +## v1.7.0 (2026-04-14) + +### Memory System v2 (Claude Code inspired) +- **Memory categories**: project, user, feedback, reference — organized facts +- **Self-skeptical prompt**: "Treat memory as hints — verify against actual code" +- **Dream cleanup**: `memory.compact()` deduplicates, keeps newest +- **Auto-compact on start**: runs when >150 facts accumulated +- **Auto-categorized detection**: 15+ patterns auto-classify facts +- **Critical fix**: MemoryStore was never initialized — all memory features were dead + +### System Prompt Hardening +- **All 30 tools described** (was 12/30) in 5 categories +- **Security section**: prompt injection detection, no untrusted execution +- **What NOT to Do**: 7 negative rules (no write for small edits, no guess, etc.) +- **Cost Awareness**: prefer cheap operations, edit over write +- **Section reorder**: important rules at end for max model attention + +### Security & Quality CI +- **cargo-audit**: dependency vulnerability scanning on every PR +- **cargo-deny**: license compliance (allowlist), supply chain checks +- **dependency-review**: block PRs adding high-severity vulns or GPL deps +- **Strict clippy**: correctness + suspicious as errors +- **Dependabot alerts**: enabled + +### New Features +- **Browser automation**: headless Playwright (navigate, screenshot, click, type, eval JS) +- **Debug mode**: hypothesis-driven structured debugging (4 phases) +- **GitHub integration**: `/gh prs`, `/gh issues`, `/gh status`, `/gh checks` +- **Agent profiles**: `/profile save/load/list` +- **Context pinning**: `/pin` — pinned messages survive compaction +- **Auto-skill creation**: auto-generate skills after complex tasks +- **Cross-session FTS search**: `/search-all` across all saved sessions +- **Configurable notifications**: `notifications` toggle + webhook (Slack/Discord) + +### UX Improvements +- **Animated spinner** during streaming/tool execution +- **Bell notification** when agent finishes +- **Categorized /help** (Navigation, Session, Agent, Code, Tools, Workflow, Config) +- **Quit confirmation** for unsaved sessions +- **Ctrl+R** reverse history search + +### Infrastructure +- **tree-sitter** AST symbol extraction (Rust, Python, JS/TS, Go) +- **arboard** cross-platform clipboard (replaces shell pbcopy/xclip) +- **GitHub templates**: bug report, feature request, PR template +- **SECURITY.md**: vulnerability reporting policy +- **274 tests**, 50% coverage, 0 warnings + ## v1.6.0 (2026-04-12) ### Managed Agents & Agentic AI diff --git a/README.md b/README.md index a41d620..3cce76e 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ magic-code "fix the bug in auth.rs" # single-shot mode ### Multi-Provider Works with **15 providers**: Anthropic, OpenAI, Gemini, Groq, DeepSeek, Mistral, xAI, OpenRouter, Together, Perplexity, Cohere, Cerebras, Ollama, LM Studio, llama.cpp. Switch mid-session with `/model`. -### 29 Built-in Tools +### 30 Built-in Tools | Tool | Description | |------|-------------| | `bash` | Execute shell commands (streaming output) | diff --git a/mc/Cargo.lock b/mc/Cargo.lock index 365d05d..0b70cf3 100644 --- a/mc/Cargo.lock +++ b/mc/Cargo.lock @@ -1097,7 +1097,7 @@ checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154" [[package]] name = "magic-code" -version = "1.6.0" +version = "1.7.0" dependencies = [ "anyhow", "arboard", @@ -1129,7 +1129,7 @@ dependencies = [ [[package]] name = "mc-config" -version = "1.6.0" +version = "1.7.0" dependencies = [ "serde", "thiserror", @@ -1139,7 +1139,7 @@ dependencies = [ [[package]] name = "mc-core" -version = "1.6.0" +version = "1.7.0" dependencies = [ "async-stream", "base64", @@ -1163,7 +1163,7 @@ dependencies = [ [[package]] name = "mc-provider" -version = "1.6.0" +version = "1.7.0" dependencies = [ "async-stream", "futures-core", @@ -1178,7 +1178,7 @@ dependencies = [ [[package]] name = "mc-tools" -version = "1.6.0" +version = "1.7.0" dependencies = [ "glob", "regex", @@ -1194,7 +1194,7 @@ dependencies = [ [[package]] name = "mc-tui" -version = "1.6.0" +version = "1.7.0" dependencies = [ "crossterm", "ratatui", diff --git a/mc/Cargo.toml b/mc/Cargo.toml index 226d9ea..44b32d9 100644 --- a/mc/Cargo.toml +++ b/mc/Cargo.toml @@ -3,7 +3,7 @@ members = ["crates/*"] resolver = "2" [workspace.package] -version = "1.6.0" +version = "1.7.0" edition = "2021" license = "MIT" publish = false diff --git a/mc/docs/guides/getting-started.md b/mc/docs/guides/getting-started.md new file mode 100644 index 0000000..4e2a5df --- /dev/null +++ b/mc/docs/guides/getting-started.md @@ -0,0 +1,66 @@ +# Getting Started + +## Install + +### Quick install (Linux/macOS) +```bash +curl -fsSL https://raw.githubusercontent.com/kienbui1995/mc-code/main/install.sh | sh +``` + +### Build from source +```bash +git clone https://github.com/kienbui1995/mc-code.git +cd mc-code/mc +cargo install --path crates/mc-cli +``` + +## Setup + +Set your API key: +```bash +export ANTHROPIC_API_KEY="your-key" +# or: OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, etc. +``` + +## First run + +```bash +magic-code # interactive TUI +magic-code "fix the bug in auth.rs" # single-shot mode +echo "explain this" | magic-code --pipe # pipe mode +``` + +## Key concepts + +- **Tools**: Agent has 30 built-in tools (bash, file ops, search, browser, debug, etc.) +- **Memory**: Persistent project facts across sessions (`/memory`) +- **Skills**: Reusable coding patterns (`.magic-code/skills/*.md`) +- **Agents**: Named agent configs (`agents/*.md`) +- **Sessions**: Save/load/branch conversations + +## Essential commands + +| Command | Description | +|---------|-------------| +| `/help` | Show all commands (categorized) | +| `/model` | Switch LLM model | +| `/plan` | Toggle plan mode (think before acting) | +| `/save` | Save current session | +| `/undo` | Undo last file changes | +| `/cost` | Show session cost | +| `/compact` | Compress context when running low | +| `/debug` | Enter structured debugging mode | +| `/gh` | GitHub integration | + +## Configuration + +Create `.magic-code/config.toml` in your project: +```toml +[default] +model = "claude-sonnet-4-20250514" +max_tokens = 8192 +provider = "anthropic" +notifications = true +``` + +See [Configuration Reference](reference/config.md) for all options. diff --git a/mc/docs/guides/memory.md b/mc/docs/guides/memory.md new file mode 100644 index 0000000..e9de209 --- /dev/null +++ b/mc/docs/guides/memory.md @@ -0,0 +1,90 @@ +# Memory System + +magic-code has a 3-layer memory system inspired by Claude Code's architecture. + +## Layer 1: Semantic Memory (Project Facts) + +Persistent key-value facts organized in 4 categories: + +| Category | What it stores | Example | +|----------|---------------|---------| +| **project** | Architecture, tools, conventions | `test_cmd = "cargo test"` | +| **user** | Preferences, role, style | `coding_style = "prefer functional"` | +| **feedback** | Corrections from user | `"always use snake_case"` | +| **reference** | File locations, endpoints | `api_endpoint = "localhost:8080"` | + +### Usage +``` +/memory # list all facts +/memory get test_cmd # get specific fact +/memory set test_cmd "pytest" # save fact +/memory delete old_key # remove fact +``` + +Agent can also use `memory_write` tool with category: +```json +{"key": "db", "value": "PostgreSQL 15", "category": "project"} +``` + +### Auto-memory +Agent automatically saves facts detected in its output: +- "project uses..." → project category +- "convention is..." → feedback category +- "running on port..." → reference category +- "user prefers..." → user category + +### Self-skeptical +Memory is injected into the system prompt with a warning: +> *Treat as hints — verify against actual code before acting.* + +This prevents hallucination from stale memory. + +### Dream cleanup +When memory exceeds 150 facts, auto-compact runs on session start: +- Deduplicates by key (keeps newest) +- Removes stale entries + +## Layer 2: Episodic Memory (Session History) + +Past conversations saved as JSON files. + +``` +~/.local/share/magic-code/sessions/ +├── last.json # auto-saved +├── my-feature.json # /save my-feature +└── debug-auth.json # /save debug-auth +``` + +### Commands +``` +/save # save session +/load # resume session +/sessions # list saved sessions +/search-all # FTS across all sessions +/fork # branch current session +/branches # list branches +``` + +## Layer 3: Procedural Memory (Skills) + +Reusable coding patterns stored as markdown files. + +``` +.magic-code/skills/ +├── setup-nextjs.md # user-created +├── deploy-aws.md # user-created +└── auto/ + └── auto-3t-8-1713000000.md # auto-generated +``` + +### Auto-skill creation +After complex successful turns (≥6 tool calls, no errors), agent auto-generates a skill file. Next time it encounters a similar task, it loads the skill. + +### Named agents +``` +agents/ +├── reviewer.md # code review specialist +└── architect.md # system design specialist +``` + +Each agent has its own model, tools, and instructions defined in YAML frontmatter. diff --git a/mc/docs/reference/config.md b/mc/docs/reference/config.md new file mode 100644 index 0000000..2e7b71a --- /dev/null +++ b/mc/docs/reference/config.md @@ -0,0 +1,68 @@ +# Configuration Reference + +## Config file locations (priority order) +1. `.magic-code/config.toml` (project — highest) +2. `~/.config/magic-code/config.toml` (user) +3. Built-in defaults (lowest) + +## All options + +```toml +[default] +# LLM +model = "claude-sonnet-4-20250514" +max_tokens = 8192 +provider = "anthropic" +base_url = "" # custom API endpoint +fallback_provider = "" # secondary provider +fallback_model = "" # secondary model + +# Permissions +permission_mode = "auto" # auto | allow | deny | prompt + +# Context +compaction_threshold = 0.8 # compact at 80% context usage +compaction_preserve_recent = 4 # keep last 4 messages + +# Notifications +notifications = true # bell + desktop notifications +notification_webhook = "" # Slack/Discord webhook URL + +# Managed Agents +[managed_agents] +enabled = false +executor_model = "claude-haiku-3-5-20241022" +executor_max_turns = 5 +max_concurrent = 3 +budget_usd = 1.0 +``` + +## Environment variables + +| Variable | Description | +|----------|-------------| +| `ANTHROPIC_API_KEY` | Anthropic API key | +| `OPENAI_API_KEY` | OpenAI API key | +| `GEMINI_API_KEY` | Google Gemini API key | +| `GROQ_API_KEY` | Groq API key | +| `DEEPSEEK_API_KEY` | DeepSeek API key | +| `OPENROUTER_API_KEY` | OpenRouter API key | +| `XAI_API_KEY` | xAI (Grok) API key | + +## CLI flags + +``` +--model LLM model +--provider Provider name +--max-tokens Max tokens per response +--resume Resume last session +--session-id Resume specific session +--pipe Read from stdin +--json JSON output mode +--yes Auto-approve (CI/CD) +--trace Debug logging +--validate-config Validate and exit +--max-budget-usd Cost limit +--max-turns Turn limit +--add-dir Grant access to extra directories +``` diff --git a/mc/docs/reference/tools.md b/mc/docs/reference/tools.md new file mode 100644 index 0000000..44ee160 --- /dev/null +++ b/mc/docs/reference/tools.md @@ -0,0 +1,58 @@ +# Tools Reference + +magic-code has 30 built-in tools organized in 5 categories. + +## Core Tools + +| Tool | Description | +|------|-------------| +| `bash` | Execute shell commands (streaming output) | +| `read_file` | Read files with optional offset/limit | +| `write_file` | Create or overwrite files | +| `edit_file` | Replace specific text (surgical edits) | +| `batch_edit` | Multiple edits to one file atomically | +| `apply_patch` | Apply unified diff patches | +| `glob_search` | Find files by pattern | +| `grep_search` | Search file contents with regex | +| `codebase_search` | Symbol-aware code search (tree-sitter) | + +## Planning & Delegation + +| Tool | Description | +|------|-------------| +| `edit_plan` | Multi-file edit plan before execution | +| `subagent` | Delegate tasks to isolated sub-agents | +| `task_create` | Start background commands | +| `task_get` | Check background task status | +| `task_list` | List all background tasks | +| `task_stop` | Stop a background task | +| `todo_write` | Write structured TODO lists | + +## Debugging & Testing + +| Tool | Description | +|------|-------------| +| `debug` | Structured debugging (hypothesize → instrument → analyze → fix) | +| `browser` | Headless browser (navigate, screenshot, click, type, eval JS) | +| `lsp_query` | Language Server queries (diagnostics, definitions) | + +## Context & Memory + +| Tool | Description | +|------|-------------| +| `memory_read` | Read persistent project facts | +| `memory_write` | Save facts (categories: project, user, feedback, reference) | +| `web_fetch` | Fetch URL content | +| `web_search` | Search the web | +| `ask_user` | Ask clarifying questions | + +## Workspace + +| Tool | Description | +|------|-------------| +| `worktree_enter` | Create isolated git worktree | +| `worktree_exit` | Exit and clean up worktree | +| `notebook_edit` | Edit Jupyter notebook cells | +| `sleep` | Wait for specified duration | +| `mcp_list_resources` | List MCP server resources | +| `mcp_read_resource` | Read MCP resource by URI |