Imported from acredsfan/ForgeMind (AGENTS.md). Install upstream with npx skills add acredsfan/ForgeMind. Copyright stays with the author.

AGENTS.md

Guidance for AI coding agents working in this repository.

Project orientation

ForgeMind is a project cognition layer for AI coding agents. Optimize for minimum high-value context necessary.

• Do not treat this repo as a chat-log archive.
• Prefer durable, reusable engineering knowledge over verbose history.
• Preserve cross-agent continuity and token efficiency.

See:

• README.md
• Context Optimization

Current repository state

Core implementation is active across Python, MCP server, and VS Code extension.

• Phase 1 (core intelligence engine) is complete and tested.
• Phase 2 (TypeScript MCP server adapter) is complete and tested.
• Phase 3 (VS Code extension scaffold) is complete and tested.
• Preserve documented subsystem boundaries when extending features.

Source of truth docs (link, don’t duplicate)

• Context Optimization
• Context Bundle Ranking
• Relevance Scoring
• Token Budgeting

When questions are covered by those docs, quote or summarize minimally and link back.

Architecture boundaries to preserve

Planned subsystem boundaries (from README.md):

• memory_core
• context_optimizer
• semantic_index
• session_engine
• mcp_server
• vscode_extension

Avoid mixing responsibilities across these components unless explicitly requested.

Working conventions for agents

• Rank context by value and relevance; avoid flooding prompts with low-signal data.
• Prefer summaries/diffs over raw logs or full-file dumps.
• Remove duplicate or stale context before proposing bundles.
• Treat critical architecture constraints as slower-decay knowledge than transient debugging notes.
• Keep recommendations concise, actionable, and verifiable.

Pitfalls to avoid

• Irrelevant context injection
• Duplicate memory inclusion
• Stale architecture guidance
• Token budget exhaustion caused by verbose historical context

Build, Test, and Run Commands

Setup

# Install in development mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Testing

# Run all tests with coverage
pytest --cov=forgemind_core --cov-report=term-missing --cov-report=html

# Run specific test file
pytest forgemind_core/tests/test_memory_store.py -v

# Run with verbose output
pytest -vv

# Minimum coverage requirement: 85%

MCP Server (Phase 2)

# Install dependencies
cd mcp_server
npm install

# Run MCP unit tests
npm test

# Build TypeScript output
npm run build

VS Code Extension (Phase 3)

# Install dependencies
cd vscode_extension
npm install

# Compile extension
npm run compile

# Run extension tests
npm test

Code Quality

# Format code
black forgemind_core/ scripts/

# Sort imports
isort forgemind_core/ scripts/

# Lint
flake8 forgemind_core/ scripts/

Running ForgeMind

# Show help
forgemind --help

# Add a memory
forgemind memory add --content "Fix websocket bug" --importance critical --tags "websocket,bug"

# List memories
forgemind memory list --limit 20

# Search memories
forgemind memory search --query "websocket reconnect"

# Generate context bundle
forgemind context --task "Implement new API" --agent copilot --max-tokens 8000

# Show statistics
forgemind stats

# View session history
forgemind session history --limit 10

# Validate full local deployment readiness (all phases)
./scripts/local_deploy_test.ps1

Implementation Status

Phase 1: Core Intelligence Engine ✓ COMPLETE

• Project structure and packaging
• Data schemas (Memory, Task, ContextBundle, Session, etc.)
• Memory core (SQLite storage, CRUD, JSON export/import)
• Relevance scoring (semantic, importance, freshness, reuse frequency)
• Context optimizer (bundling, compression, token budgeting)
• Semantic index (embeddings with sentence-transformers)
• Session engine (session tracking and memory usage)
• CLI tool (all commands for memory, context, sessions)
• Core tests (memory_store, scorer, builder, sessions)

Phase 2: MCP Server Integration ✓ COMPLETE

• TypeScript/Node.js MCP server
• Endpoints for context generation, memory/session management
• Tool adapter boundary preserved via Python JSON bridge

Phase 3: VS Code Extension ✓ COMPLETE

• Sidebar memory view with refresh command
• Context bundle preview command + copy action
• Settings UI (CLI path, default token budget, default agent)

Directory Structure

forgemind_core/
  __init__.py
  cli.py                          # CLI interface
  memory_core/
    __init__.py
    memory_store.py               # SQLite storage layer
  context_optimizer/
    __init__.py
    relevance_scorer.py           # Relevance scoring engine
    context_builder.py            # Context bundling and compression
  semantic_index/
    __init__.py
    embeddings.py                 # Embedding store and search
  session_engine/
    __init__.py
    session_tracker.py            # Session lifecycle management
  mcp_bridge.py                  # JSON bridge for MCP adapter
  schemas/
    __init__.py
    models.py                     # Data models (Memory, Task, etc.)
  tests/
    __init__.py
    test_memory_store.py
    test_relevance_scorer.py
    test_context_builder.py
    test_session_tracker.py

mcp_server/
  src/
    index.ts                      # MCP stdio server entrypoint
    bridgeClient.ts               # Persistent Python bridge process client
    toolHandlers.ts               # Tool schemas + dispatch + validation
  tests/
    toolHandlers.test.ts

vscode_extension/
  src/
    extension.ts                  # Activation and command wiring
    services/forgeMindService.ts  # CLI adapter for extension features
    providers/memoryTreeProvider.ts
    panels/contextPreviewPanel.ts
  src/test/
    forgeMindService.test.ts

Test Coverage

Current coverage target: 85%+

• memory_core/memory_store.py — SQLite CRUD, JSON import/export
• context_optimizer/relevance_scorer.py — Scoring formulas, weight combinations
• context_optimizer/context_builder.py — Bundling, compression, token budgeting
• session_engine/session_tracker.py — Session lifecycle, statistics
• schemas/models.py — Data model serialization

If you add implementation files later

When modifying or extending code, ensure:

1. New code follows the existing patterns in its subsystem
2. Tests are added/updated to maintain 85%+ coverage
3. CLI receives updates for new major features
4. Documentation is kept in sync with code changes