Architecture Decision Records (hx-agent-notes)
Relevant source files
The following files were used as context for generating this wiki page:
Architecture Decision Records (ADRs) within the hx-agent-notes framework provide a structured methodology for capturing the "why" behind technical choices. This system ensures that AI agents and human developers access historical reasoning, constraints, and evolved logic rather than just viewing current code states. By separating current facts (reference/) from historical justifications (decisions/), the project maintains a clear evolutionary trajectory for the software architecture.
Sources: blog/2026/10/07/01-AI代码质量.md:175-185, ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md:7-15
1. Documentation Taxonomy and Structure
The documentation system categorizes information into distinct directories to prevent "knowledge rot" and ensure AI agents can retrieve specific context efficiently. Each document focuses on a single theme and separates current facts from historical context.
| Directory | Purpose | Content Type |
|---|---|---|
tutorials/ | Procedural guides | "How-to" instructions |
reference/ | Current technical facts | API contracts, schemas, current state |
architecture/ | High-level design | System overviews and structural layouts |
decisions/ | Design rationale | ADRs: Why specific choices were made |
archive/ | Deprecated documentation | Outdated information for historical audit |
Sources: blog/2026/10/07/01-AI代码质量.md:175-195
1.1 Documentation Flow Diagram
The following diagram illustrates how raw information flows into specialized storage to become structured knowledge.
2. Memory Layer Architecture
The memory system uses a four-layer architecture to handle different levels of data persistence and relevance. This structure allows the system to differentiate between clear facts and fuzzy conversation context.
- Session Metadata: Captures environment info (time zone, device) for the current turn.
- Structured Profile (JSON): Stores clear facts (user preferences, tech stacks) using overwrite updates to maintain a Single Source of Truth (SSOT).
- Conversation Summary: Periodically condenses chat history into topic lists to provide long-term context without exhausting token budgets.
- Working Memory: Maintains a sliding window of recent interactions for immediate processing.
Sources: ai-docs/003-AI/004-记忆/001-对话记忆与知识库增量沉淀/index.md:50-75
2.1 Ledger, Views, and Policy System
The "Memory Triad" manages how data is stored, processed, and retrieved:
- Ledger: An append-only record of every raw fact and event. It acts as a "black box" for debugging.
- Views: Derived projections of the ledger (e.g., Knowledge Graphs, Profile Cards) formatted for AI consumption.
- Policy: The control engine that decides when to record, when to retrieve, and when to forget information.
Sources: ai-docs/003-AI/004-记忆/001-对话记忆与知识库增量沉淀/index.md:80-95
3. AI-First Writing and Maintenance Rules
Documents in the hx-agent-notes system follow "AI-First" principles, prioritizing machine readability and retrieval over human browsing.
3.1 Core Principles
- Self-Containment: Every note must be understandable without relying on back-links.
- For Future AI Prefix: Every document starts with a 2-3 sentence summary immediately after the frontmatter.
- Bitemporal Timestamps: Records distinguish between when a fact was true in reality (
valid_time) and when the system learned it (learned_time). - Sentinel Sections: Uses
<!-- @generated -->and<!-- @user -->tags to separate automated updates from manual edits, preventing data loss during regeneration.
Sources: ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md:50-70, ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md:120-135
3.2 Metadata Handling in UI
The React frontend (Docusaurus) identifies knowledge base pages using the /knowledge-base path. It injects specific AI metadata headers and relationship diagrams to visualize document connections.
// src/theme/DocItem/Layout/index.tsx:37-45
export default function DocItemLayout ({ children }: Props): ReactNode {
const docTOC = useDocTOC();
const { metadata } = useDoc();
const location = useLocation();
// Detect if the page is an AI knowledge base page
const isAIDocs = location.pathname.includes('/knowledge-base');
// ...
{isAIDocs && <AIDocHeader />}
Sources: src/theme/DocItem/Layout/index.tsx:37-65
4. Agent Skill Integration
Agent skills (like hx-agent-notes) are governed by context budgets and trigger engineering. A skill's activation is determined solely by its name and description fields in the metadata.
- Context Budget: The skill正文 (SKILL.md) must be under 500 lines or 5000 tokens.
- Trigger Engineering: The
descriptionfield must include specific keywords and "When to Use" scenarios, as the main body is not loaded until the skill triggers. - Gradual Disclosure: Large datasets or schemas reside in
references/and are only read by the agent upon specific demand defined in theSKILL.mdindex.
Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:70-100, ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:135-155
4.1 Skill Structure Table
| Level | Content | Budget |
|---|---|---|
| Level 1 | name + description | ~100 words |
| Level 2 | SKILL.md (Core logic) | < 500 lines |
| Level 3 | references/, scripts/ | No hard limit |
Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:76-85
5. Automated Taxonomy and Sidebar Generation
The system uses automated scripts to maintain the taxonomy defined in ADRs. generateAiDocsSidebar.js scans the ai-docs/ directory and applies specific icons (ai-folder.svg / ai-doc.svg) based on file types and folder contents. It strips numerical prefixes from folder names to create clean UI labels.
Sources: scripts/generateAiDocsSidebar.js:15-30, scripts/generateAiDocsSidebar.js:45-60
Conclusion
Architecture Decision Records in hx-agent-notes serve as a critical bridge between ephemeral conversation logs and static codebases. By utilizing bitemporal tracking, sentinel-guarded file updates, and a structured hierarchy of memory (Ledger/Views/Policy), the system ensures that AI agents operate with full context, avoiding past failures and adhering to established design patterns.