feat(context): add context-maintainer and context-search skills

[divitkashyap]

Submitted by: divitkashyap

What

Added context-maintainer and context-search — a two-part skill + MCP tool system for persistent project context across AI agent sessions.
Why this matters: Every new chat session starts with zero memory. The agent wastes time re-scanning repos, burning through context on file walks instead of actual work. Context files persist across sessions so agents jump-start instantly.

Components

Skill: context-maintainer — instructs the agent when and how to write context
Skill: context-search — instructs the agent when and how to read context
MCP server: context-maintainer-mcp — file operations for context maintenance (8 tools)
MCP server: context-search-mcp — search + export for context retrieval (6 tools)

File Structure Created

.context/
├── project.md # What it does, how to run
├── architecture.md # System design, data flow
├── decisions.md # Choices made and why
├── active-files.md # Files being worked on + freshness + git history
├── stale-files.md # Deprecated approaches (flagged)
├── goals.md # Long term + short term goals + session history
├── relationships.md # Key dependencies
└── recent-commits.md # Last 10 commits (cheap git log)

Key Ideas

1. Context That Survives Sessions

Context files are written to .context/ in the project root. New sessions read them — no re-scanning.

2. Token-Efficient Context

Agents don't load full context files into every response. Pattern:

• get_active_context → returns previews (not full contents)
• search_context → targeted lookups
• goals.md → always read first, always kept short (YAML frontmatter, max ~50 lines)

3. Freshness Scoring

active-files.md tracks:

• HIGH: modified < 24h
• MEDIUM: modified < 7 days
• LOW: modified > 7 days
  Agents prioritize HIGH freshness files — less wasted context on stale code.

4. Stale Tracking

Deprecated approaches get flagged (not deleted) in stale-files.md. Prevents repeating old mistakes without losing history.

5. Dynamic Goals — Long-term vs Short-term

goals.md format:

# Long-term Goals
- Build a real-time data pipeline that processes 10k events/sec
- Migrate from REST to gRPC by Q3
# Short-term Goals
- [ACTIVE] Fix authentication middleware bug
- [DONE] Add rate limiting to API endpoints
# Session History
- [2026-04-05] Completed: Rate limiting implementation

When context window is ~70% full, agent checkpoints → context clears, next session resumes instantly.

6. Git History Without Burn

active-files.md includes per-file git history (last commit, last modified). The agent knows what's changed without running git commands every prompt. Git history calls are <50ms — cheap.

7. Trigger Strategy — Significant Changes Only

Never update after every edit. Updates fire when:

• After a git commit (meaningful work done)

• 30 lines modified across files in one session

• Context window hits ~70% threshold
• Session ends

8. .context/ Gitignored by Default

Personal context stays private. User opts in to commit with gitignore_remove. Team sharing is a choice, not a default.

9. Optional QMD Integration

On first search_context call, tool checks if QMD is available:

• If yes: asks user permission → runs qmd embed → enables hybrid semantic search
• If no: falls back to grep (still functional)

10. Obsidian Export

export_to_vault(context_path, vault_path) — one-way sync to Obsidian vault. User gets graph view of relationships — optional, not required.

MCP Tools

context-maintainer: init_context, update_context, checkpoint_goals, flag_stale, promote_stale, gitignore_add, gitignore_remove, gitignore_status
context-search: search_context, get_active_context, get_file_context, export_to_vault, prune_context, check_qmd

Installation

MCP servers (for local testing before PyPI publish):

python3 skills/context-maintainer/scripts/server.py
python3 skills/context-search/scripts/server.py

After PyPI publish:

uvx context-maintainer-mcp
uvx context-search-mcp

OpenCode config (~/.config/opencode/opencode.json):

{
  "mcp": {
    "context-maintainer": {
      "type": "local",
      "command": ["uvx", "context-maintainer-mcp"],
      "enabled": true
    },
    "context-search": {
      "type": "local",
      "command": ["uvx", "context-search-mcp"],
      "enabled": true
    }
  }
}

Testing
Validated: python .claude/skills/pr-review/scripts/validate_skills.py ✅ All 14 skills pass.
Notes

• MCP servers use Python stdlib only — no external dependencies
• QMD integration is optional — grep fallback always works
• Goals.md uses YAML frontmatter for machine-parseable metadata
• Generic enough to work with any AI agent (MiniMax, Claude, Cursor, Codex) — not MiniMax-specific
• Single PR for all 4 components — skills are useless without MCP servers and vice versa