.Aayan-Mem

A Two-Brain Architecture for Zero-Hallucination AI Coding

.Aayan-Mem is an open-source memory and reasoning framework that forces AI coding agents to prove their logic before writing code. It eliminates hallucinations, prevents token waste, and creates a permanent, auditable timeline of every architectural decision.

Zero dependencies. Pure Node.js. $0 cost.

🧠 The Problem

AI coding agents hallucinate. They reference files that don't exist, follow stale logic, make decisions without comparing alternatives, and burn thousands of tokens reading entire files when they only need two lines.

.Aayan-Mem solves this by splitting the agent's mind into two hemispheres with strict operational rules.

🏗️ Architecture

.Aayan-Mem/
├── Agent/                          ← THE ACCOUNTABILITY ENGINE
│   ├── rules.md                    ← 8 operational rules + CLI reference
│   ├── session-template.md         ← Canonical decision log template
│   ├── session-counter.json        ← Auto-incrementing session tracker
│   ├── decision-index.md           ← 1-line summary pointers (no token bombs)
│   ├── decision-logs/
│   │   └── session-1.md            ← Full decision log with comparison matrix
│   └── tools/
│       ├── search.js               ← Snippet search (4-line context buffer)
│       ├── coldstart.js            ← 5-line briefing + stale decision scanner
│       ├── validate.js             ← Contradiction detection across Memory
│       ├── verify-paths.js         ← File path existence checker
│       └── status.js               ← Unified system health dashboard
└── Memory-&-Context/               ← THE RECALL ENGINE
    ├── App-Goal.md                 ← What are we building and why
    ├── Stack.md                    ← Framework, language, DB, deployment
    ├── Context-index.md            ← Pointers, preferences, API key locations
    ├── Design-Guidelines.md        ← UI/UX rules (glassmorphism, animations)
    └── rules.md                    ← Measurable code quality thresholds

How the Two Brains Work

| Brain | Purpose | Contains | |-------|---------|----------| | Agent (Accountability Engine) | Forces the AI to simulate, compare, and document reasoning before coding | Decision logs, comparison matrices, session history, operational rules | | Memory-&-Context (Recall Engine) | Provides the single source of truth about the project's state | Tech stack, design guidelines, file locations, code quality rules |

🚀 Quick Start

Prerequisites

• Node.js (v14+)

Usage

From the project root:

# Interactive mode — presents a menu
.\a-mem

# Direct commands
.\a-mem coldstart              # Session initialization briefing
.\a-mem find "auth|supabase"   # Snippet search across all files
.\a-mem validate               # Scan for contradictions
.\a-mem verify                 # Check if referenced paths exist
.\a-mem status                 # Full system health check
.\a-mem help                   # Show all commands

Note: On PowerShell, use .\a-mem. On bash/zsh, use ./a-mem.js or node a-mem.js.

📋 CLI Command Reference

| Command | What It Does | |---------|-------------| | .\a-mem | Launch interactive mode with numbered menu | | .\a-mem coldstart | Read first 5 lines of each Memory file + check for stale decisions | | .\a-mem find "term" | Search all .Aayan-Mem files with 4-line context buffer | | .\a-mem validate | Detect contradictions and duplicate definitions across Memory | | .\a-mem verify | Check if file paths referenced in Memory exist on disk | | .\a-mem status | Run all health checks in one unified report | | .\a-mem help | Show all available commands |

🎯 The 8 Operational Rules

| # | Rule | Purpose | |---|------|---------| | 1 | Cold Start | Run .\a-mem coldstart at the start of every session | | 2 | Contradiction Check | Run .\a-mem validate after any Memory update | | 3 | Task Complexity Tiers | Tier 1 (trivial) = skip simulation. Tier 2 (feature) = 1-line log. Tier 3 (architecture) = full 3-path comparison matrix | | 4 | Session Management | Use session-counter.json and session-template.md for consistent logs | | 5 | Hallucination Guard | Verify file existence before referencing Memory paths | | 6 | Proof-of-Read | Echo 3 key facts from coldstart to prove comprehension | | 7 | Pre-Commit Checklist | Sessions can't close without Post-Implementation Verification | | 8 | Zero Token Leaks | No Read-Leaks, No Write-Leaks, No Thought-Leaks |

🔬 Decision Simulation Flow

Task arrives
     │
     ▼
┌─────────────┐
│ Classify     │
│ Tier 1/2/3   │
└──────┬──────┘
       │
  ┌────┴────────────────────────┐
  │            │                │
  ▼            ▼                ▼
Tier 1       Tier 2           Tier 3
Execute      Log path +       Full 3-path
immediately  1 sentence       simulation
             reasoning        + comparison
                              matrix
                                │
                                ▼
                         ┌──────────────┐
                         │ Path A vs B  │
                         │   vs C       │
                         │ Score each   │
                         │ on criteria  │
                         └──────┬───────┘
                                │
                                ▼
                         Log winner +
                         rejected paths +
                         exact reasoning

🛡️ Anti-Hallucination Features

• Snippet Search: Never reads full files — returns only matching lines ± 2 lines of context
• Contradiction Scanner: Detects conflicting facts across Memory files
• Path Verifier: Proves referenced files exist on disk before the agent uses them
• Stale Decision Scanner: Flags decisions past their Review-By date
• Anti-Drift Headers: Every Memory file tracks Last-Modified-By and Last-Modified-Session
• Changelog Enforcement: Every Memory file has a ## Changelog section for version history
• Proof-of-Read: Agent must echo back facts from coldstart to prove it didn't just run and ignore

📄 License

This project is licensed under the MIT License.

🤝 Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b feature/new-tool)
3. Follow the existing code commenting style (JSDoc headers on all .js files)
4. Test with .\a-mem status before submitting
5. Open a Pull Request

Built by Aayan — because AI should reason, not guess.