Jonny (Self-Learning AI Assistant) - Amazon Q CLI

What is Amazon Q CLI?

Amazon Q CLI: AI assistant that runs in your terminal

Chat with AI to get help with commands, code, AWS
Translate natural language → shell commands
Persistent memory across sessions via agents
Extensible with custom agents and knowledge bases

Directory Structure

~/.aws/amazonq/
├── cli-agents/              # Agent configuration files
│   ├── default.json         # Default agent config
│   ├── jonny.json           # Custom agent config
│   └── agent_config.json.example
├── profiles/                # Agent-specific data/resources
│   ├── default/
│   │   └── context.json
│   ├── jonny.md             # Persistent memory file
│   └── CAGENT/              # Example: specialized agent
├── knowledge_bases/         # Semantic search storage
│   └── jonny_13db4e44f333bf41/
│       ├── contexts.json    # Knowledge context metadata
│       └── models/          # Vector embeddings
└── .cli_bash_history        # Command history

Key Concepts

Agent

Agent: Configuration that defines AI behavior and capabilities

JSON file in cli-agents/ directory
Controls prompt, tools, resources, behavior
Can be global (~/.aws/amazonq/cli-agents/) or local (.amazonq/cli-agents/)

Profile

Profile: Directory containing agent-specific data

Located in profiles/ directory
Stores persistent memory, context, scripts
Named to match agent name

Resource

Resource: File loaded into agent context on startup

Defined in agent’s resources[] array
Typically markdown files with persistent memory
Example: file://~/.aws/amazonq/profiles/jonny.md

Knowledge Base

Knowledge Base: Semantic search storage for files/directories

Stores vector embeddings for fast search
Persists across sessions
Accessed via knowledge tool

Tools

Tools: Functions the AI can call

fs_read: Read files/directories
fs_write: Create/edit files
execute_bash: Run shell commands
use_aws: AWS CLI operations
knowledge: Semantic search
delegate: Launch background agents

Agent Configuration (JSON)

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "jonny",
  "description": "Custom agent with persistent memory",
  "prompt": "Custom instructions for AI behavior",
  "tools": ["*"],
  "allowedTools": ["fs_read", "knowledge"],
  "resources": [
    "file://~/.aws/amazonq/profiles/jonny.md"
  ]
}

Key fields:

name: Agent identifier
prompt: Custom system instructions
tools: Available tools (["*"] = all tools)
allowedTools: Tools that don’t require confirmation
resources: Files loaded into context on startup

Memory Persistence Across Sessions

How Jonny remembers across sessions:

1. Resource Loading (Automatic)

{
  "resources": [
    "file://~/.aws/amazonq/profiles/jonny.md"
  ]
}

What happens:

You start: q chat --agent jonny
Agent reads jonny.json config
Loads jonny.md file into AI context
AI has access to all memory content
Memory persists even after /clear or /quit

2. Memory Update Workflow

During conversation:

You: "Remember I prefer AWS profile user-nishinoo"

Jonny: [Updates jonny.md with fs_write tool]
       [Runs: knowledge update --path jonny.md]

What happens:

Jonny writes new information to jonny.md
Jonny updates knowledge base with new content
File persists on disk
Next session: Resource loads updated memory

3. Knowledge Base Sync

Critical step after updating memory file:

knowledge update --path /Users/nishinoo/.aws/amazonq/profiles/jonny.md

Why this matters:

Resource loading: Reads file on startup
Knowledge base: Semantic search across sessions
Both must stay in sync for consistent memory

Without knowledge update:

Next session: Resource loads new memory ✓
Knowledge search: Returns old memory ✗

With knowledge update:

Next session: Resource loads new memory ✓
Knowledge search: Returns new memory ✓

4. Memory Persistence Levels

Method	Survives /clear	Survives /quit	Searchable
Conversation context	No	No	No
Resource file	Yes	Yes	No
Knowledge base	Yes	Yes	Yes

Conversation context:

Temporary memory during chat
Lost on /clear or /quit

Resource file (jonny.md):

Persistent memory on disk
Loaded every session
Not searchable (must read entire file)

Knowledge base:

Persistent memory with semantic search
Survives all restarts
Can search specific topics

Agent Loading Priority

Two-tier loading system:

Local agents (project-specific): .amazonq/cli-agents/
Global agents (user-wide): ~/.aws/amazonq/cli-agents/

Loading behavior:

# Uses default agent
q chat

# Uses specified agent (searches local → global)
q chat --agent jonny

# If jonny.json exists locally, uses local version
# Otherwise, uses global version from ~/.aws/amazonq/cli-agents/

Common Commands

# Start chat with default agent
q chat

# Start chat with specific agent
q chat --agent jonny

# Resume previous conversation
q chat --resume

# List available agents
q agent list

# Create new agent
q agent create my-agent

# Edit existing agent
q agent edit jonny

# Set default agent
q agent set-default jonny

# Validate agent config
q agent validate ~/.aws/amazonq/cli-agents/jonny.json

Chat Commands (Inside q chat)

/clear          Clear conversation (memory persists)
/quit           Exit chat
/save           Save conversation
/load           Load saved conversation
/context        Show current context
/help           Show available commands

Knowledge Base Commands

Inside q chat:

# Add file to knowledge base
knowledge add --name "AWS Notes" --value ~/aws-notes.md

# Add directory to knowledge base
knowledge add --name "Project Docs" --value ~/my-project/docs/

# Search knowledge base
knowledge search --query "S3 bucket policy"

# List all knowledge contexts
knowledge show

# Remove knowledge context
knowledge remove --name "AWS Notes"

# Update existing context (after modifying file)
knowledge update --path ~/aws-notes.md --name "AWS Notes"

# Check background operation status
knowledge status

Tool Permissions

allowedTools vs tools:

{
  "tools": ["*"],              // All tools available
  "allowedTools": ["fs_read"]  // Only fs_read runs without confirmation
}

Behavior:

Tools in allowedTools: Execute immediately
Tools NOT in allowedTools: Ask for confirmation first
Security: Prevents accidental destructive operations

Memory Update Example

Scenario: Learning new preference

You: "I prefer minimal code implementations"

Jonny: [Internally]
       1. fs_write: Update jonny.md with new preference
       2. knowledge update: Sync knowledge base
       
       "I've updated my memory. I'll provide minimal code from now on."

[Next session]
You: "Write a function to read a file"

Jonny: [Loads jonny.md resource on startup]
       [Sees: "User prefers minimal code"]
       
       "Here's a minimal implementation..."

Workflow Example

# 1. Create custom agent
q agent create study-helper

# 2. Edit agent config
# Add resources, customize prompt, set allowed tools

# 3. Create memory file
echo "# Study Notes" > ~/.aws/amazonq/profiles/study-helper.md

# 4. Add resource to agent config
# "resources": ["file://~/.aws/amazonq/profiles/study-helper.md"]

# 5. Start chat with agent
q chat --agent study-helper

# 6. Add knowledge base (inside chat)
knowledge add --name "AWS Docs" --value ~/aws-docs/

# 7. Agent updates memory during conversation
# (automatically writes to study-helper.md)

# 8. Next session: memory persists
q chat --agent study-helper
# Agent loads study-helper.md automatically

Agent vs Profile vs Knowledge Base

Component	Purpose	Location	Persistence
Agent	Define behavior	`cli-agents/*.json`	Config only
Profile	Store agent data	`profiles/[name]/`	Files/scripts
Resource	Load into context	Defined in agent	Every session
Knowledge Base	Semantic search	`knowledge_bases/`	Across sessions

Directory Permissions

# Agent configs (user-only read/write)
-rw------- jonny.json

# Memory files (user-only read/write)
-rw------- jonny.md

# Knowledge base (user-only access)
drwx------ knowledge_bases/

Security: Only your user can read/write agent configs and memory

Debugging

# Check Q CLI installation
q doctor

# Verbose output
q chat --verbose

# Check agent loading
q agent list

# Validate agent config
q agent validate ~/.aws/amazonq/cli-agents/jonny.json

# Check knowledge base status
# (inside q chat)
knowledge status

Notes

Agents are loaded from local directory first, then global
Resources are loaded on every agent startup (automatic memory persistence)
Knowledge bases persist across sessions and /clear commands
allowedTools controls which tools run without confirmation
Memory files (resources) survive /clear and /quit (stored on disk)
Knowledge base is best for large documents (semantic search)
Resources are best for small context (loaded every time)
Always run knowledge update after modifying memory file to keep search in sync

What is Amazon Q CLI?#

Directory Structure#

Key Concepts#

Agent#

Profile#

Resource#

Knowledge Base#

Tools#

Agent Configuration (JSON)#

Memory Persistence Across Sessions#

1. Resource Loading (Automatic)#

2. Memory Update Workflow#

3. Knowledge Base Sync#

4. Memory Persistence Levels#

Agent Loading Priority#

Common Commands#

Chat Commands (Inside q chat)#

Knowledge Base Commands#

Tool Permissions#

Memory Update Example#

Workflow Example#

Agent vs Profile vs Knowledge Base#

Directory Permissions#

Debugging#

Notes#

Table of Contents