ctxmem agent skill

Stop losing track of architectural decisions and project context between coding sessions. Developers often struggle with agents that forget previous discussions or hallucinate outdated patterns in growing repositories. This skill implements a Git-native memory layer that keeps your project knowledge where it belongs: in the repository.

What it does

• Persistent recall uses local keyword search to retrieve relevant project history before starting new tasks.
• Context management generates task-specific context within token budgets to prevent LLM noise.
• Decision tracking records architectural choices and rationales with a built-in superseding mechanism for updates.
• Git-native storage saves memories in JSONL format within your repo for easy versioning and sharing.
• State reconciliation identifies when current code conflicts with historical records to ensure accuracy.

How it works

1. Inspection checks for the presence of the ctxmem CLI and repository configuration files.
2. Setup installs the local utility and configures persistent agent instructions for automatic recall.
3. Retrieval runs targeted queries against the local memory store to gather evidence for the current prompt.
4. Recording captures new decisions or corrections using specific types and file path associations.

Frameworks & tools

This skill requires Python 3.8+ with SQLite FTS5 support and Git. It operates locally using the ctxmem CLI tool.

Why this beats prompting it yourself

Manual prompts rely on the agent's short-term context window which clears every session. This skill provides a structured, searchable database that persists across tool restarts and different developer environments.

Use cases

• Onboard new agents or developers to a complex codebase with historical context.
• Prevent regressions by surfacing previous architectural "why" decisions.
• Synchronize project knowledge across a team using standard Git workflows.
• Manage large-scale refactors where decisions must be tracked over multiple days.

Known limitations

Requires local execution permissions for Python and Git. Does not store secrets or credentials. Memory recall performance depends on the quality of recorded titles and descriptions.