Summary

Addresses AI coding agent amnesia caused by context window limitations and "lost in the middle" phenomena, which degrade performance and waste developer time. auto-memory provides a zero-dependency, read-only CLI tool that leverages GitHub Copilot CLI's local SQLite session store for instant, low-token recall of past sessions and files. It targets developers using AI coding assistants, offering significant time savings and improved agent efficiency by enabling persistent context recall.

How It Works

This project functions as an AI agent's "page fault handler," retrieving precise context from disk when needed. It directly queries the ~/.copilot/session-store.db SQLite database (using FTS5 for search) in a read-only, WAL-safe manner. By executing lightweight commands like session-recall files --json --limit 10, it injects relevant session history or file access data into the agent's prompt using minimal tokens (~50). This approach avoids the need for complex setups, external databases, or agent modifications, integrating seamlessly via instruction files.

Quick Start & Requirements

• Install: pip install auto-memory or clone the repository and run ./install.sh.
• Prerequisites: GitHub Copilot CLI must be installed and configured. On Windows, WSL2 is recommended, and the Copilot CLI Session Store needs to be enabled via /experimental command within a Copilot CLI session. Requires Python standard library only.
• Links: Setup and integration details are in deploy/install.md and copilot-instructions-template.md. Schema validation guidance is in UPGRADE-COPILOT-CLI.md.

Highlighted Details

• 200x ROI: Achieves a claimed 50-token recall versus 10,000+ tokens for manual context retrieval or re-explanation.
• Time Savings: Aims to recover approximately 68 minutes per day lost to AI agent re-orientation and context degradation.
• Zero Dependencies: Implemented entirely using Python's standard library (sqlite3, json, argparse), simplifying installation and maintenance.
• Progressive Disclosure: Employs tiered recall strategies (Tier 1: ~50 tokens, Tier 2: ~200 tokens, Tier 3: ~500 tokens) to optimize token usage based on query complexity.

Maintenance & Community

Developed by Desi Villanueva, the project welcomes contributions via GitHub issues and pull requests. A session-recall health command provides a diagnostic dashboard for monitoring operational status. Specific community channels like Discord or Slack are not detailed in the README.

Licensing & Compatibility

The project is released under the MIT License, permitting broad use, modification, and distribution, including for commercial purposes and integration into closed-source applications. It is designed for compatibility with AI agents that support instruction files, such as GitHub Copilot CLI, Claude Code, Cursor, and Aider.

Limitations & Caveats

auto-memory is strictly a local-only solution and does not offer cross-machine synchronization. It is not a vector database and relies solely on SQLite's FTS5 capabilities. The tool recalls user actions and session context, not inherent system knowledge or project documentation. Users must ensure Copilot CLI's session store is enabled, and be prepared to run schema checks following Copilot CLI updates.