AI-Assisted Development with U-AMOS 2.0

AI coding assistants like Cursor, Windsurf, and Claude Code are powerful, but they often struggle with large codebases. They "hallucinate" imports, forget context, and overwrite existing patterns.

To solve this, we created U-AMOS 2.0 (Universal AI Memory Operating System).

This guide explains how to use U-AMOS to make AI your perfect pair programmer.

🧠 What is U-AMOS?

U-AMOS stands for Universal AI Memory Operating System. It's a structured way to manage the "memory" and "context" of your AI assistant.

The Problem it Solves

1. Hallucination: AI making up imports or functions that don't exist.
2. Context Amnesia: AI forgetting what you decided in the last session.
3. Token Waste: AI re-reading the entire codebase for every small task.

The Solution: Memory Tiers

U-AMOS breaks down project context into Tiers, so the AI only loads what it needs.

graph BT
    Hot[🔥 HOT TIER<br/>.memory/40-active.md<br/>Active Task] --> Warm
    Warm[☀️ WARM TIER<br/>Architecture & Patterns<br/>Load On-Demand] --> Cold
    Cold[❄️ COLD TIER<br/>Project Identity<br/>Load Rarely]
    style Hot fill:#ff7b72,stroke:#333,stroke-width:2px,color:#fff
    style Warm fill:#d29922,stroke:#333,stroke-width:2px,color:#fff
    style Cold fill:#0969da,stroke:#333,stroke-width:2px,color:#fff

Example: Hot Memory (40-active.md)

This is what a real "Hot Context" file looks like. The AI reads this at the start of every session to know exactly where we left off.

# Active Context

## Current Focus
**Implementation**: We are building the "Premium Paywall" screen using RevenueCat.

## Active Sprint / Tasks
- [x] Configure RevenueCat keys in .env
- [x] Create PaywallScreen.tsx UI
- [ ] Connect "Restore Purchases" button (Current Task)
- [ ] Test purchase flow in Sandbox

## Open Questions / Blockers
- Need to verify if we use "monthly" or "annual" offering ID.

Pro Tip: You keep this file updated. The AI reads it to "download" your brain state.

🛠️ Tooling & Setup

For Cursor Users

The project comes with a .cursorrules file pre-configured. This file automatically instructs Cursor to:

1. Read the Hot Memory files (.memory/40-active.md) at the start of a chat.
2. Consult the Context Map (ai_rules/context_map.md) before searching.
3. Follow the Anti-Hallucination Checklist.

For Windsurf / Claude Users

You'll see a CLAUDE.md or agents.md file in the root. Use the provided "Startup Sequence" prompt when you begin a session:

Run the mandatory startup sequence:
1. Read ai_rules/globalRules.md
2. Read .memory/40-active.md
3. Run the Anti-Hallucination Checklist

🛡️ Anti-Hallucination Protocol

To prevent the AI from generating broken code, U-AMOS enforces a 7-Point Checklist that the AI must run internally before writing a single line of code.

flowchart TD
    Start([User Request]) --> Check1{File Exists?}
    Check1 -- No --> Stop([❌ STOP & Ask])
    Check1 -- Yes --> Check2{Component Exists in Inventory?}
    Check2 -- Yes --> UseIt[Use Existing Component]
    Check2 -- No --> CreateIt[Create & Update Inventory]
    CreateIt --> Check3{Using t-key for Text?}
    UseIt --> Check3
    Check3 -- No --> FixText[Refactor to i18n]
    Check3 -- Yes --> Check4{Using Logger?}
    FixText --> Check4
    Check4 -- Yes --> WriteCode([✅ Write Code])

1. ✅ Does the file exist? (Verify paths)
2. ✅ Did I check src/ui/README.md? (Don't recreate existing UI components)
3. ✅ Did I check src/services/README.md? (Don't recreate existing services)
4. ✅ Is the import path correct? (Use absolute @/ imports)
5. ✅ Does the function exist? (Verify usage)
6. ✅ Am I using t('key')? (No hardcoded text)
7. ✅ Am I using logger? (No console.log)

🚦 Workflow: How to Code with AI

Step 1: Start a Session

Open your AI chat and type:

"Start Update active task: Implement Profile Screen in .memory/40-active.md"

Step 2: Navigate with Context Map

Instead of letting the AI search blindly, tell it where to look using the Context Map (ai_rules/context_map.md).

"Check ai_rules/context_map.md to find the relevant feature folder for 'Profile'."

Step 3: Implement with Generators

We have pre-built Generators in ai_rules/generators/. These are step-by-step implementation guides.

Example Usage:

"I need to add a subscription screen. Read ai_rules/generators/paywall_generator.md and follow the steps to implement it."

🎭 Prompt Engineering: Examples

Here are refined prompts to get the best results from U-AMOS.

Scenario A: Implementing a Missing Feature

Context: You generated your app_features_list.md and identified a feature marked as "NEW" or "CUSTOMIZE".

Good Prompt (U-AMOS Style):

"I want to implement the 'Daily Quote' feature from my features list.

1. It should display a quote on the Home Screen.
2. Users can toggle a 'heart' icon to save to favorites.
3. Favorites must persist offline using Redux Persist.
4. Follow the existing pattern in src/features/todos/."

Scenario B: Creating a New Feature

Bad Prompt: "Make a settings screen." Good Prompt (U-AMOS Style):

"I want to create a Settings feature.

1. Check src/features/README.md to see existing patterns.
2. Check src/ui/README.md for reusable components.
3. Create a plan in implementation_plan.md first.
4. Use the Feature-First structure: src/features/settings/."

Scenario B: Fixing a Bug

Bad Prompt: "Fix the login error." Good Prompt (U-AMOS Style):

"I'm seeing a login error.

1. Read .memory/40-active.md for context.
2. Check src/features/auth/api/auth.api.ts.
3. Verify the error handling against ai_rules/rules/best-practices.md."

Scenario C: Refactoring

Bad Prompt: "Clean up this code." Good Prompt (U-AMOS Style):

"Refactor ProfileScreen.tsx.

1. Apply the rules from ai_rules/rules/design-system.md.
2. Ensure all text uses t('keys').
3. Replace inline styles with Restyle props."

📚 Rule Packs

U-AMOS uses Rule Packs to keep the context window light. Instead of loading all rules, load only what you need.

• UI Work? -> Load ai_rules/rules/design-system.md
• Testing? -> Load ai_rules/rules/testing.md
• Backend? -> Load ai_rules/rules/offline.md

Tell the AI: "Load the Design System rules before rewriting this component."