PRINCIPLES.DM

# Technical Principle Analysis: Passive Context & Long Memory Mechanisms

The "Passive Context Long Memory" claimed by this project is not some black-box model training, but a deep utilization of AI IDE native capabilities through the lens of **Prompt Engineering**.

## Principle 1: IDE Hook Injection

**Principle**: Leverage the priority of the AI client's "Auto-start Configuration".

- **Mechanism**: Tools like Cursor read `.cursorrules` before the session starts, splicing it at the very front of the System Prompt.
- **Operation**: The framework plants "instruction stakes" in these files, requiring the AI to read `AGENTS.md` as the first step. Through the IDE's native mechanism, the project's "worldview" and "governance rules" are injected into the AI's Active Context before the user types a single word.
- **Value**: Solves the "cold start" problem of re-explaining project background for every new conversation.

## Principle 2: Cognitive Funneling

**Principle**: Replace long text descriptions with high-density metadata to reduce Token entropy.

- **Mechanism**: `AGENTS_INDEX.yaml` provides a machine-readable addressing space.
- **Operation**:
    1. **Compressed Indexing**: `AGENTS.md` uses register-mapping style tags (e.g., `{modern-python}`, `{glassmorphism}`). This activates specific knowledge in the LLM's **associative memory** from its training data without needing thousands of words in the prompt.
    2. **Path Convergence**: When retrieving project knowledge, the AI no longer traverses the entire file tree ($O(N)$), but directly hits the corresponding protocol file under `.agents/` via the index ($O(1)$).
- **Value**: Significantly saves Token consumption while ensuring the AI's meta-cognition (Task/Plan) stays strongly consistent with the user's dialogue language through "Cognitive Mirroring".

## Principle 3: The Sandwich Prompt

**Principle**: Resolve long-conversation forgetting using LLM positional bias (Recency Bias & Primacy Bias).

- **Mechanism**: Architecture implemented in `make_prompt.py`.
- **Structure**:
    1. **Layer 1 (Primacy)**: [SYSTEM INSTRUCTION] - Defines identity and global bans.
    2. **Layer 2 (Memory)**: `context/memory.md` (ADR) - Injects past architectural decisions (e.g., "disable eval") as static background.
    3. **Layer 3 (State)**: `PROJECT_STATUS.md` - Injects current real-time progress.
    4. **Layer 4 (Recency)**: [USER QUERY] - The user's current question.
- **Value**: Even if conversation history is pruned due to length, the `memory.md` stored in the file system is "re-fed" to the AI in every turn. This extracts "long memory" from the unstable conversation flow into a controlled L2 cache layer.

## Principle 4: Agentic BOOT_SEQUENCE

**Principle**: Upgrade static documents into "executable governance programs".

- **Mechanism**: State machine logic in `BMAD_BOOTSTRAP.md`.
- **Operation**: This protocol doesn't just tell the AI "how to do it", but also how to "self-check" (e.g., check Node.js environment, detect if `bmad/` folder exists). This turns the AI from a passive assistant into an active "gatekeeper" of the project environment.

(以下是中文解释)
---

# 技术原理分析：被动上下文与长记忆机制 (Passive Context & Long Memory)

本项目宣称的“被动上下文长记忆”并非某种黑盒模型训练，而是通过**工程化指令（Prompt Engineering）**视角对 AI IDE 原生能力的深度压榨。

## 原理一：系统指令扩展 (IDE Hook Injection)

**原理**：利用 AI 客户端的“自启动配置”优先级。

- **机制**：Cursor 等工具会在会话开始前读取 `.cursorrules`，将其拼接在系统提示词（System Prompt）的最前端。
- **运作过程**：框架在这些文件中埋下“指令桩”，要求 AI 第一步必读 `AGENTS.md`。这通过 IDE 的原生机制，在用户未输入任何文字前，就已经把项目的“世界观”和“治理规则”注入到了 AI 的激活上下文（Active Context）中。
- **价值**：解决了每次新对话都要重新解释项目背景的“冷启动”问题。

## 原理二：认知镜像与漏斗 (Cognitive Funneling)

**原理**：通过高密度元数据替代长文本描述，降低 Token 熵值。

- **机制**：由 `AGENTS_INDEX.yaml` 提供机器可读的寻址空间。
- **运作过程**：
    1. **压缩索引**：`AGENTS.md` 使用类似寄存器映射的标签（如 `{modern-python}`, `{glassmorphism}`），通过 LLM 的**联想记忆**直接激活其训练数据中的特定知识，而无需在 Prompt 中写几千字教程。
    2. **路径收敛**：AI 在检索项目知识时，不再遍历庞大的文件树（O(N)），而是根据索引直接命中 `.agents/` 下对应的协议文件（O(1)）。
- **价值**：极大节省了 Token 消耗，同时通过“认知镜像”确保 AI 的元认知（Task/Plan）与用户对话语言保持强一致。

## 原理三：“三明治”提示词架构 (The Sandwich Prompt)

**原理**：利用 LLM 的位置偏差（Recency Bias & Primacy Bias）解决长对话遗忘问题。

- **机制**：在 `make_prompt.py` 中实现的架构。
- **结构**：
    1. **层 1 (首因)**：[SYSTEM INSTRUCTION] - 定义身份和全局禁令。
    2. **层 2 (记忆)**：`context/memory.md` (ADR) - 将过去的架构决策（如“禁用 eval”）作为静态背景注入。
    3. **层 3 (状态)**：`PROJECT_STATUS.md` - 注入当前的实时进度。
    4. **层 4 (近因)**：[USER QUERY] - 用户当前的问题。
- **价值**：即使对话记录由于太长被裁剪（Pruning），存储在文件系统中的 `memory.md` 也会在每一轮对话中被重新“喂给”AI。这相当于把“长记忆”从不稳定的对话流中提取出来，放到了一个受控的 L2 缓存层中。

## 原理四：Agentic 引导序列 (BOOT_SEQUENCE)

**原理**：将静态文档升级为“可执行的治理程序”。

- **机制**：`BMAD_BOOTSTRAP.md` 中的状态机逻辑。
- **运作过程**：这套协议不仅告诉 AI “怎么做”，还告诉它如何“自检”（如检查 Node.js 环境、检测 `bmad/` 目录是否存在）。这让 AI 从一个被动回答问题的助手，变成了主动维护项目环境的“看门人”。

---
*Generated by Antigravity Research Subagent*