AI Development Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• session_manager.py
• tests/test_integration.py
• memory-bank/memories/67944906-43bc-4c85-9424-f2261850bc97.md
• memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md

These guidelines define the operational standards for AI agents interacting with the sequential-thinking-mcp-v2 repository. The project currently exists in a transitional state between an older markdown-only implementation and a target layered memory architecture. These rules ensure consistency in reasoning, memory persistence, and context management across both states.

Sources: CLAUDE.md:3-12, README.md:1-7

Architecture Principles

The system operates on a "Cloud-Assisted, Local-First" fallback model. While cloud providers perform heavy lifting for embeddings and summarization, the local environment serves as the primary source of truth and retrieval for indexed artifacts.

Memory Layering

The memory system splits data across three specialized layers to prevent retrieval conflicts:

• Canonical Human Truth: Markdown files (design docs, ADRs, module maps) remain the official human-maintained truth.
• Document Retrieval: The qmd component indexes and retrieves canonical documentation.
• Semantic Artifacts: The Zvec component manages retrieval for promoted machine memory and non-document artifacts like investigation summaries.

Sources: CLAUDE.md:18-24, README.md:52-64

Component Interaction

The diagram below illustrates how external tool calls flow through the system layers to the persistence engine.

Reasoning and Memory Lifecycle

AI agents must distinguish between ephemeral thoughts and durable conclusions. The system enforces a strict promotion gating process.

Memory Promotion Rules

Only conclusions that meet specific criteria become durable machine memory. You must not store raw chain-of-thought as long-term memory by default. Promotion requires:

1. Verifiable evidence.
2. High confidence (typically >0.8).
3. Stability beyond the current sub-task.
4. Identifiable reuse value for future sessions.

Sources: CLAUDE.md:28-35, README.md:66-74

The Reasoning Lifecycle

Token and Context Management

The system treats token limits as a primary design constraint. Agents must actively manage their context window to prevent performance degradation.

Policy Defaults

Metric	Value	Purpose
Active Context Ceiling	64K tokens	Maximum operational context
Compaction Trigger	45K tokens	Threshold to start compression
Retrieval Scope	Task-specific	Prevents context flooding

Sources: CLAUDE.md:43-48, README.md:76-88

Management Procedures

1. Retrieve on Demand: Do not preload the entire codebase; scope retrieval to the active task.
2. Checkpointing: Summarize state at sub-task boundaries.
3. Handoff Bundles: Pass summaries and handoff bundles between agents instead of raw transcripts.
4. Batch Indexing: Queue qmd indexing updates in batches rather than triggering them on every small change.

Sources: CLAUDE.md:43-52, README.md:83-88

Implementation Standards

When modifying the codebase or adding tools, follow these technical constraints.

Core Persistence Logic

The UnifiedSessionManager handles the lifecycle of thoughts and memories. It validates inputs before writing to the markdown-based memory-bank.

def add_thought(
    self,
    content: str,
    branch_id: str = "",
    confidence: float = 0.8,
    dependencies: str = "",
    explore_packages: bool = False,
) -> str:
    if not self.current_session:
        raise NoActiveSessionError("Cannot add thought without an active session")

    # Validate confidence bounds
    if not (0 <= confidence <= 1):
        raise ValidationError("Thought confidence must be between 0 and 1")

    thought = Thought(
        session_id=self.current_session.id,
        content=content.strip(),
        confidence=confidence,
        # ... additional initialization
    )
    self.current_session.thoughts.append(thought)
    self._save_session_to_file(self.current_session)
    return thought.id

Sources: session_manager.py:172-209

Testing Focus

Developers must expand the test suite to cover the target architecture boundaries. Focus areas include:

• Promotion Gating: Validating that only high-confidence items are stored as memories.
• Handoff Integrity: Ensuring generate_handoff creates valid recovery artifacts.
• Fallback Behavior: Testing local retrieval performance when cloud providers are unavailable.
• Metadata Validation: Ensuring artifact confidence and staleness states remain accurate.

Sources: CLAUDE.md:63-71, memory-bank/memories/67944906-43bc-4c85-9424-f2261850bc97.md

Summary of Operational Tools

The current implementation utilizes a 12-tool surface, but the target architecture emphasizes higher-level orchestration tools.

Tool Name	Action	Source File
retrieve_context	Fetches scoped context for active tasks	CLAUDE.md
promote_memory	Gated transition of thoughts to durable storage	README.md
generate_handoff	Creates a summary bundle for agent transitions	CLAUDE.md
search_docs	Queries the canonical markdown layer via qmd	README.md
record_decision	Persists architecture choices to the memory-bank	session_manager.py

Sources: README.md:90-100, CLAUDE.md:58-61, session_manager.py:338-356

The AI Development Guidelines facilitate the transition to a more scalable, layered memory architecture while maintaining the stability of the current markdown-only implementation. By following these rules, agents ensure that reasoning remains bounded, memory remains validated, and context remains manageable.