feat: change session storage to project-local ./.chat-sessions

BREAKING CHANGE: Session storage location changed from ~/agent-conversations
to ./.chat-sessions in current working directory.

Why This Change:
- Context separation - sessions from different projects are now separate
- Project-local - sessions stay with the project they belong to
- Simpler - no configuration needed, predictable behavior
- Team-friendly - sessions can optionally be committed to version control

Implementation:
- Removed save_location from config (no longer configurable)
- Updated SessionManager default to Path.cwd() / ".chat-sessions"
- Simplified ChatLoop - no longer reads save_location from config
- Removed save_location prompts from config wizard
- Updated all documentation (README, CONFIG.md)
- Updated all help text and error messages
- Fixed tests to no longer expect save_location config

Migration:
- Old sessions remain in ~/agent-conversations as markdown files
- No automatic migration - clean break
- Users can manually copy if needed

Files Changed:
- SessionManager: Now uses ./.chat-sessions by default
- ChatConfig: Removed save_location from defaults
- config_wizard: Removed save_location prompts
- display_manager: Updated auto-save message
- chat_loop: Removed save_location config reading
- README.md: Updated session location examples
- docs/CONFIG.md: Updated paths documentation
- Tests: Updated to not expect save_location

Examples:
Before: ~/agent-conversations/ (global, configured)
After:  ./.chat-sessions/ (project-local, fixed)

All tests passing (318 passed, 13 skipped)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: jwesleye

README.md

@@ -16,7 +16,7 @@ A feature-rich, interactive CLI for **AWS Strands** agents with token tracking,
 - 🎵 **Harmony Support** - Specialized processing for OpenAI Harmony format (gpt-oss models)
 - 📜 **Command History** - Navigate previous queries with ↑↓ arrows (persisted to `~/.chat_history`)
 - ✍️ **Multi-line Input** - Type `\\` to enter multi-line mode with Ctrl+D to cancel and ↑ to edit previous lines
-- 💾 **Session Management** - Save conversations as clean markdown files in `~/agent-conversations/`
+- 💾 **Session Management** - Save conversations as clean markdown files in `./.chat-sessions/` (project-local)
 - 📋 **Copy Commands** - Copy responses, queries, code blocks, or entire conversations to clipboard
 - 💰 **Token Tracking** - Track tokens and costs per query and session
 - 📝 **Prompt Templates** - Reusable prompts from `~/.prompts/`
@@ -311,13 +311,13 @@ You: Now let's add authentication
 
 **View saved conversations:**
 
-Conversations are saved as clean markdown files in `~/agent-conversations/`:
+Conversations are saved as clean markdown files in `./.chat-sessions/` (in current directory):
 ```bash
-ls -lh ~/agent-conversations/
+ls -lh ./.chat-sessions/
 # Shows files like: simple_sally_20251230_110627.md
 
 # View a conversation
-cat ~/agent-conversations/simple_sally_20251230_110627.md
+cat ./.chat-sessions/simple_sally_20251230_110627.md
 ```
 
 Each saved session includes an auto-generated summary that enables fast, context-aware resumption without replaying all queries.
@@ -328,7 +328,7 @@ Each saved session includes an auto-generated summary that enables fast, context
 chat_loop --list-sessions
 ```
 
-Sessions are saved to `~/agent-conversations/` by default (configurable).
+Sessions are saved to `./.chat-sessions/` in your current working directory, providing context separation between different projects.
 
 ### Copy Commands
 

docs/CONFIG.md

@@ -81,10 +81,11 @@ File system locations:
 
 ```yaml
 paths:
-  save_location: ~/agent-conversations    # Conversation exports
   log_location: .logs                      # Log files
 ```
 
+**Note:** Conversation sessions are now saved to `./.chat-sessions/` in the current working directory (project-local, not configurable). This provides context separation - sessions from different projects are kept separate.
+
 ### Behavior
 
 Runtime behavior:
@@ -271,7 +272,7 @@ sessions:
 
 **Saved session structure:**
 ```
-~/agent-conversations/         # Default location (configurable)
+./.chat-sessions/              # Project-local (in current directory)
 ├── myagent_20250126_143022.json    # Machine-readable
 ├── myagent_20250126_143022.md      # Human-readable
 └── .index.json                      # Fast lookup index
@@ -281,11 +282,10 @@ sessions:
 ```yaml
 features:
   auto_save: true              # Required for session persistence
-
-paths:
-  save_location: ~/agent-conversations  # Where sessions are stored
 ```
 
+Sessions are saved to `./.chat-sessions/` in your current working directory, providing context separation between different projects.
+
 **Usage:**
 ```bash
 # List all saved sessions
@@ -312,8 +312,6 @@ agents:
     features:
       auto_save: true
       show_tokens: true
-    paths:
-      save_location: ~/code-conversations/clara
     behavior:
       timeout: 300.0
     ui:
@@ -540,8 +538,7 @@ features:
   readline_enabled: boolean
 
 paths:
-  save_location: string  # Path with ~ and $VAR expansion
-  log_location: string
+  log_location: string  # Path with ~ and $VAR expansion
 
 behavior:
   max_retries: integer   # 0-10 recommended

src/basic_agent_chat_loop/chat_config.py

@@ -44,7 +44,6 @@ class ChatConfig:
             "readline_enabled": True,
         },
         "paths": {
-            "save_location": "~/agent-conversations",
             "log_location": "~/.chat_loop_logs",
         },
         "behavior": {
@@ -363,8 +362,8 @@ def initialize_default_config() -> Path:
 # ============================================================================
 # PATHS - File system locations
 # ============================================================================
+# Note: Conversations saved to ./.chat-sessions (project-local, not configurable)
 paths:
-  save_location: ~/agent-conversations    # Where to save conversations
   log_location: ~/.chat_loop_logs          # Where to write logs (in home directory)
 
 # ============================================================================
@@ -417,8 +416,6 @@ def initialize_default_config() -> Path:
 #     features:
 #       auto_save: true
 #       show_tokens: true
-#     paths:
-#       save_location: ~/my-agent-conversations
 
 agents: {}
 """

src/basic_agent_chat_loop/chat_loop.py

@@ -635,14 +635,8 @@ def __init__(
         )
 
         # Setup session manager for conversation persistence
-        sessions_dir = (
-            self.config.expand_path(
-                self.config.get("paths.save_location", "~/agent-conversations")
-            )
-            if self.config
-            else Path.home() / "agent-conversations"
-        )
-        self.session_manager = SessionManager(sessions_dir=sessions_dir)
+        # Sessions are saved to ./.chat-sessions in current directory
+        self.session_manager = SessionManager()
 
         # Setup Harmony processor if agent uses Harmony format
         self.harmony_processor = None
@@ -2895,17 +2889,8 @@ def main():
 
     # Handle session management commands
     if args.list_sessions:
-        # List sessions and exit
-        config = get_config(config_path=args.config) if args.config else get_config()
-        sessions_dir = (
-            config.expand_path(
-                config.get("paths.save_location", "~/agent-conversations")
-            )
-            if config
-            else Path.home() / "agent-conversations"
-        )
-
-        session_manager = SessionManager(sessions_dir=sessions_dir)
+        # List sessions and exit (from ./.chat-sessions in current directory)
+        session_manager = SessionManager()
         sessions = session_manager.list_sessions(limit=50)
 
         if sessions:
@@ -2924,7 +2909,7 @@ def main():
             print(f"        {Colors.system('chat_loop <agent> --resume <session_id>')}")
         else:
             print(f"\n{Colors.system('No saved sessions found')}")
-            print(f"Sessions will be saved to: {sessions_dir}")
+            print("Sessions will be saved to: ./.chat-sessions")
 
         sys.exit(0)
 

src/basic_agent_chat_loop/components/config_wizard.py

@@ -90,7 +90,6 @@ def reset_config_to_defaults() -> Optional[Path]:
                 "spinner_style": "dots",
             },
             "paths": {
-                "save_location": "~/agent-conversations",
                 "log_location": "~/.chat_loop_logs",
             },
         }
@@ -650,15 +649,8 @@ def _configure_paths(self):
 
         self.config["paths"] = {}
 
-        # save_location
-        current_save_location = (
-            self.current_config.get("paths.save_location", "~/agent-conversations")
-            if self.current_config
-            else "~/agent-conversations"
-        )
-        print("Where to save conversations (supports ~ for home directory)")
-        save_loc = input(f"Save location [{current_save_location}]: ").strip()
-        self.config["paths"]["save_location"] = save_loc or current_save_location
+        # Conversations are now saved to ./.chat-sessions (project-local)
+        # No configuration needed
 
         # log_location
         current_log_location = (

src/basic_agent_chat_loop/components/display_manager.py

@@ -128,12 +128,7 @@ def display_banner(self):
             print()
             print(Colors.DIM + "Configuration loaded" + Colors.RESET)
             if self.auto_save:
-                save_loc = self.config.get(
-                    "paths.save_location",
-                    "~/agent-conversations",
-                    agent_name=self.agent_name,
-                )
-                print(f"  Auto-save: enabled → {save_loc}")
+                print("  Auto-save: enabled → ./.chat-sessions")
 
         print("=" * 60)
 

src/basic_agent_chat_loop/components/session_manager.py

@@ -65,9 +65,9 @@ def __init__(self, sessions_dir: Optional[Path] = None):
 
         Args:
             sessions_dir: Directory for session files
-                         (defaults to ~/agent-conversations)
+                         (defaults to ./.chat-sessions in current directory)
         """
-        self.sessions_dir = sessions_dir or Path.home() / "agent-conversations"
+        self.sessions_dir = sessions_dir or Path.cwd() / ".chat-sessions"
         self.index_file = self.sessions_dir / ".index.json"
 
     def _ensure_sessions_dir(self) -> bool:

tests/unit/test_config_wizard.py

@@ -465,21 +465,23 @@ class TestConfigurePaths:
     @patch("builtins.input")
     def test_configure_paths_defaults(self, mock_input, wizard):
         """Test configuring paths with defaults."""
-        mock_input.side_effect = ["", ""]
+        mock_input.side_effect = [""]
 
         wizard._configure_paths()
 
-        assert wizard.config["paths"]["save_location"] == "~/agent-conversations"
+        # save_location no longer configurable (uses ./.chat-sessions)
+        assert "save_location" not in wizard.config["paths"]
         assert wizard.config["paths"]["log_location"] == "~/.chat_loop_logs"
 
     @patch("builtins.input")
     def test_configure_paths_custom_values(self, mock_input, wizard):
         """Test configuring paths with custom values."""
-        mock_input.side_effect = ["~/custom/conversations", "~/custom/logs"]
+        mock_input.side_effect = ["~/custom/logs"]
 
         wizard._configure_paths()
 
-        assert wizard.config["paths"]["save_location"] == "~/custom/conversations"
+        # save_location no longer configurable (uses ./.chat-sessions)
+        assert "save_location" not in wizard.config["paths"]
         assert wizard.config["paths"]["log_location"] == "~/custom/logs"