A.MEM

Zero-Hallucination Memory Architecture for AI Coding Agents

A.MEM forces your AI coding agent to prove its logic before writing a single line of code.

It treats memory as a living Epistemic State Machine — not a static document store. Every fact is tracked, every path rejected is logged permanently, and every decision is auditable for the lifetime of the project.

Documentation · Quick Start · CLI Reference · npm Package

The Problem

You give your AI agent a task. It confidently writes 80 lines of code — to a file you deleted three days ago. No error. No warning. Just silent failure.

This happens because agents have no tether. They generate statistically probable tokens, not verified truths. They re-suggest libraries you already rejected. They forget architectural decisions you spent hours reasoning through.

A.MEM is the tether.

How It Works

A.MEM splits the agent's context into two distinct engines:

| Engine | Role | Contains | |--------|------|---------| | Recall Engine | Static truth. What exists, what's banned, what's decided. | App-Goal.md, Stack.md, Rejection-Ledger.md, rules.md | | Accountability Engine | Dynamic reasoning. Simulate before you code. | Decision logs, comparison matrices, session counter, session index |

Before any task, the agent runs a-mem coldstart to load the ground truth. Before any complex task, it opens a session log and documents 3 architectural paths, scores them, and records the rejected ones permanently. Only then does it write code.

🚀 Quick Start

1. Install globally:

npm install -g aayan-mem

2. Initialize your project:

cd your-project
a-mem init

The wizard auto-detects your tech stack from package.json and scaffolds the full .Aayan-Mem/ directory.

3. Start your first session:

a-mem coldstart

📋 CLI Reference

Session Workflow

| Command | Description | |---------|-------------| | a-mem init | Run the setup wizard. Auto-detects framework, language, and styling from package.json. | | a-mem coldstart | Load session briefing: reads all Memory files + scans for stale decisions. Run before every task. | | a-mem coldstart "topic" | Filtered briefing — only shows facts matching the topic keyword. | | a-mem new "title" | Open a new decision log with an auto-incremented session ID. | | a-mem close [N] | Close session N. Blocks if post-implementation checkboxes are empty. | | a-mem sync | Rebuild decision-index.md from all session logs. |

Diagnostics & Guards

| Command | Description | |---------|-------------| | a-mem status | Full system health dashboard with color-coded integrity alerts. | | a-mem integrity | Scans for UTF-8 corruption, mixed line endings, version drift. Supports --strict for CI pipelines. | | a-mem validate | Detects contradictions in ESM facts across all Memory files. | | a-mem verify | Hallucination Guard: verifies every backtick-wrapped path exists on disk. | | a-mem verify --scan-logs | Also scans decision logs for stale path references. |

Discovery & State

| Command | Description | |---------|-------------| | a-mem esm | Epistemic State Machine report: Confirmed Facts vs Assumptions vs Rejections. | | a-mem find "term" | RegEx-capable search across all memory files with 4-line context buffer. | | a-mem find "term" --in memory | Scope search to Memory-&-Context/ only. | | a-mem find "term" --in decisions | Scope search to decision logs only. | | a-mem log | Visual, chronological decision timeline. | | a-mem list | Inventory of all tracked files with sizes and last-modified dates. | | a-mem help | Full command reference with usage examples. |

🏗️ Project Structure

After running a-mem init, your project will contain:

.Aayan-Mem/
│
├── Agent/                         ← THE ACCOUNTABILITY ENGINE
│   ├── rules.md                   ← 8 operational rules (non-negotiable)
│   ├── decision-index.md          ← Auto-synced 1-line pointers (no token bombs)
│   ├── session-counter.json       ← Monotonic session ID tracker
│   ├── session-template.md        ← Canonical decision log format
│   ├── decision-logs/
│   │   └── session-1.md           ← Full reasoning log with comparison matrix
│   └── tools/                     ← The CLI toolchain (10 Node.js scripts)
│       ├── coldstart.js
│       ├── esm.js
│       ├── integrity.js
│       ├── search.js
│       ├── status.js
│       ├── sync-index.js
│       ├── ui.js
│       ├── validate.js
│       ├── verify-paths.js
│       └── ...
│
└── Memory-&-Context/              ← THE RECALL ENGINE
    ├── App-Goal.md                ← Project objective + success criteria
    ├── Stack.md                   ← Tech stack as ESM facts [FACT-001]
    ├── Context-index.md           ← File map, env vars, API locations
    ├── Rejection-Ledger.md        ← Banned libraries/paths [REJ-001]
    └── Design-Guidelines.md       ← UI/UX rules and component standards

🧠 The Epistemic State Machine (ESM)

A.MEM doesn't store text — it tracks verified truth.

Every fact in your Memory files is tagged with a semantic type:

| Tag | Meaning | Example | |-----|---------|---------| | [FACT-001] | A confirmed, witnessed truth | React v18.2 is the UI framework | | [ASSUMPTION] | A temporary belief pending verification | Auth module uses Clerk | | [REJ-001] | An explicitly rejected path or library | Prisma ORM — rejected: too heavy | | [WITNESS: session-3] | The session that proved a fact | Traces each belief to its origin |

Running a-mem esm surfaces a live report of your project's belief state, categorized by confidence level. Running a-mem validate cross-checks your session logs against this state to detect contradictions before they become bugs.

🛡️ Anti-Hallucination System

| Feature | How It Works | |---------|-------------| | Path Verifier | Before any file is referenced, a-mem verify checks it physically exists on disk. Supports Unix and Windows paths. | | Rejection Ledger | Every discarded library or architecture pattern is logged permanently. The agent can never re-suggest them. | | Contradiction Scanner | a-mem validate reads all Memory files and flags conflicting facts (e.g., "uses Tailwind" vs "no Tailwind in stack"). | | Stale Decision Scanner | a-mem coldstart flags any session log past its Review-By date for re-validation. | | Content Integrity | a-mem integrity checks for UTF-8 corruption, mixed CRLF/LF line endings, and unfilled template placeholders. | | Proof-of-Read | The agent must echo 3 key facts from coldstart before proceeding — proving it didn't skip context loading. |

🔄 The Standard Workflow

Every new session
      │
      ▼
  a-mem coldstart          ← Load ground truth. Prove you read it.
      │
      ▼
  a-mem new "task title"   ← Open a decision log
      │
      ▼
  Simulate 3 paths          ← Write them in the session log matrix
  Score each path
  Record rejected paths     ← They go in the Rejection Ledger
      │
      ▼
  Write code
      │
      ▼
  a-mem verify              ← Did all referenced paths survive?
  a-mem validate            ← Did we violate any Memory constraints?
      │
      ▼
  a-mem close [N]           ← Blocks if checklist is incomplete
      │
      ▼
  a-mem sync                ← Rebuild the index

⚙️ The 8 Operational Rules

These rules are embedded in Agent/rules.md and enforced by the CLI:

| # | Rule | Enforcement | |---|------|-------------| | 1 | Cold Start | Run a-mem coldstart at the start of every session | a-mem coldstart required | | 2 | Contradiction Check | Run a-mem validate after every Memory update | CI --strict flag | | 3 | Tier Classification | Tier 1 (trivial) = execute. Tier 2 (feature) = 1-line log. Tier 3 (architecture) = full 3-path matrix | Session template | | 4 | Session Management | Every Tier 2/3 task gets a session log with an auto-incremented ID | a-mem new | | 5 | Witness Protocol | Every path referenced must be verified on disk before use | a-mem verify | | 6 | Proof-of-Read | Agent must echo 3 facts from coldstart before proceeding | Manual check | | 7 | Closure Gate | Sessions cannot close with empty post-implementation checkboxes | a-mem close | | 8 | Zero Token Leaks | No full file reads. No over-simulation. Surgical snippets only. | a-mem find |

📦 Package Info

{
  "name": "aayan-mem",
  "version": "2.0.1",
  "bin": { "a-mem": "./a-mem.js" },
  "dependencies": {}
}

• Size: ~120KB installed (all toolchain + scaffolding)
• Runtime: Node.js 18+ (no build step, no transpilation)
• OS: Windows, macOS, Linux — fully cross-platform
• Privacy: Zero network requests. All data is local to your machine.

📄 License

MIT © Aayan

Built because AI should reason, not guess.

⭐ Star on GitHub · 📦 npm · 📖 Docs