Open Source CLI Node 18+ Cross-platform Clean Commit

awesome-context-engine

Portable repo memory and context optimization for AI coding agents

npx awesome-context-engine

GitHub npm README

Keep AI coding context fresh without manual prompt wrangling. awesome-context-engine initializes repository memory, scans existing repositories to baseline context, indexes your project, syncs compact context files, and keeps durable memory for tools like Claude Code, Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Aider, OpenClaw, Factory Droid, Trae, Hermes, Kiro, Google Antigravity, Cline, and Continue.

Persistent Memory

Store reusable project context in .awesome-context.

Flexible Sync

Use low-RAM on-demand sync, optional hooks, or optional watch mode.

Token Efficient

Generate compact, high-signal context for AI sessions.

Memory Commands

Add, search, summarize, and prune project memory with dedicated CLI commands.

Local-first

Run entirely in-repo without external service requirements.

Safe Defaults

Preserve existing memory files and merge integration rules safely.

Cross-IDE CLI

Use the same ace command flow across editors and terminals.

Strict Security Mode

Block context sync when secret-like content is detected using --strict.

Why Context Optimization Matters

The table below is a SWE-bench-inspired demonstration framework across models, assistants, and task types. Values are estimated/example results for planning and communication, not universal guarantees.

Scenario	Model	Assistant	Repo / Task	Raw Tokens	ACE Tokens	Reduction	Quality	Completion Delta
API bugfix triage	GPT-5 class	VS Code Copilot Chat	TypeScript SaaS monorepo	12,400	6,900	44.4%	Higher relevance	+8-12% (estimated)
Auth refactor	Claude class	Claude Code	Node service repo	9,100	5,200	42.9%	Higher relevance	+6-10% (estimated)
UI regression fix	Gemini class	Cursor	React frontend	7,800	4,600	41.0%	Higher relevance	+5-9% (estimated)

For reproducible local measurement, run ace benchmark and use ace benchmark --json --compact for dashboards.

Methodology and interpretation guide: README benchmark methodology.

Quick Start

Run the CLI from your repository root and follow the guided setup.

npx awesome-context-engine init to initialize context and AI integration files.
npx awesome-context-engine scan to baseline repository context for existing codebases.
npx awesome-context-engine index to refresh project structure mapping.
npx awesome-context-engine sync to regenerate compact AI context.
npx awesome-context-engine context:pack src/cli.ts to start focused, low-noise AI tasks.

First 5 Minutes

Use this short flow to start safe edits quickly with context-first commands.

ace init to bootstrap map, graph, cache, and context artifacts.
ace context:pack src/cli.ts to generate an edit-ready context brief.
ace context:impact src/cli.ts to check direct and transitive impact before changes.
ace context:refresh after meaningful edits to keep memory and metadata current.
ace learn:capture --from exports/session.txt --summary "first pass on cli changes" to save useful, reusable learning.

Advanced Commands

Use these advanced commands for memory maintenance and validation workflows.

ace memory add --type preference --text "Use clear markdown docs" to store reusable memory.
ace memory search --query "markdown docs" to retrieve relevant memory by intent.
ace memory summarize to condense stale memory into summaries.
ace memory prune to remove duplicates and low-value memory.
ace cache:status to inspect ACE Cache tracked files, changes, and hit rate.
ace cache:clear to remove .awesome-context/cache.json and force a cold rebuild.
ace graph --full to bypass incremental mode and rebuild graph/context from source.
ace learn:capture --file exports/session.txt --summary "release checklist" to capture an ACE Genesis experience.
ace learn:recall "release workflow" to retrieve relevant prior experiences and preferences.
ace learn:suggest, ace learn:skill, and ace learn:reflect to draft and improve reusable skills.
npx awesome-context-engine scan --dry-run --verbose to preview baseline context updates with no file writes.

ACE Cache

ACE Cache accelerates repeat runs by reusing extraction results for unchanged files while keeping source files as the single source of truth. Cache data is stored in .awesome-context/cache.json and can be safely deleted at any time.

ACE Genesis

ACE Genesis is the local learning layer for repeated work. It captures approved task experiences, recalls relevant prior context, suggests reusable skills, drafts those skills under .awesome-context/skills/drafts/, and tracks reflection notes over time.

ace learn:capture captures a task trace from file, stdin, or text input with redaction.
ace learn:recall ranks memory by similarity, recency, project fit, and task type.
ace learn:profile shows the current local user/project model.
ace learn:forget removes selected experiences, suggestions, or profile entries.

Refresh Strategy

Default workflow is low-RAM and explicit: run ace context:pack <file> before focused work and ace sync after meaningful file changes. Use ace auto only if you want continuous watch mode on higher-spec machines.

Latest Updates

New: scan command baselines context for existing repositories before ongoing auto updates.
New: scan --dry-run previews baseline context generation without changing repository files.
New: persistent memory commands support add/search/summarize/prune workflows.
Auto mode performs index + sync on startup and re-runs on repository and editable context updates.

Compatibility

Designed for macOS, Ubuntu/Linux, and Windows with Node.js 18+.

Credits

Thanks to the open-source maintainers and AI tooling communities that shaped context-first workflows.