cameron.stream / co
A React Native app for the ultimate thinking partner.
fork atom

docs: update README to reflect current co implementation and features

cameron.stream 9a1a80da 225dc295

+78 -63
+78 -63
README.md
··· 1 - # Co - Knowledge Management Assistant 1 + # co 2 2 3 - Co is a single-agent knowledge management assistant built with Letta's memory framework. Each user gets their own persistent Co agent that learns and remembers across conversations. 3 + A minimalist chat interface for Letta AI agents. Each user gets their own persistent co agent that learns and remembers across conversations. 4 4 5 5 ## Features 6 6 7 - - 🤖 **Single Agent Model**: One Co agent per user, tagged with `co-app` 7 + - 🤖 **Single Agent**: One co agent per user, automatically created on first login 8 8 - 🧠 **Persistent Memory**: Advanced memory blocks that evolve over time 9 - - 💬 **Real-time Streaming**: Token-by-token message streaming 9 + - 💬 **Smooth Streaming**: Token-buffered streaming (50 FPS) for consistent text appearance 10 + - 🎨 **Polished UI**: Clean, minimal interface with animated message transitions 11 + - 🌓 **Theme Toggle**: Switch between light and dark modes 10 12 - 🔧 **Tool Support**: Web search, archival memory, conversation search 11 13 - 📱 **Cross-platform**: iOS, Android, and Web support via React Native + Expo 12 - - 🎨 **Modern UI**: Clean, intuitive interface with memory viewer 13 - - 🔒 **Secure**: API token storage with AsyncStorage 14 + - 🔒 **Secure**: API token storage with AsyncStorage/SecureStore 14 15 15 16 ## Architecture 16 17 17 - Co uses a simplified single-agent architecture: 18 + co uses a simplified single-agent architecture: 18 19 19 20 1. **Login**: User enters Letta API key 20 - 2. **Agent Discovery**: App searches for agent with `co-app` tag using `client.agents.list(tags=["co-app"])` 21 - 3. **Agent Creation**: If no Co agent exists, creates one with the `createCoAgent()` function 22 - 4. **Chat**: User chats directly with their Co agent 21 + 2. **Agent Discovery**: App searches for agent with `co-app` tag 22 + 3. **Auto-creation**: If no co agent exists, creates one automatically 23 + 4. **Chat**: User chats directly with their co agent 23 24 24 - ### Co Agent Configuration 25 + ### co Agent Configuration 25 26 26 - Co is created with: 27 + co is created with: 27 28 - **Model**: `anthropic/claude-sonnet-4-5-20250929` 28 29 - **Tools**: `send_message`, `archival_memory_insert`, `archival_memory_search`, `conversation_search`, `web_search`, `fetch_webpage` 29 30 - **Memory Blocks**: 30 - - `persona`: Co's adaptive personality 31 + - `persona`: co's adaptive personality 31 32 - `human`: User profile that evolves 32 33 - `approach`: Conversation and memory approach 33 34 - `working_theories`: Active theories about the user ··· 52 53 53 54 # Start development server 54 55 npm start 56 + 57 + # For production performance (recommended) 58 + npm run web:prod 55 59 ``` 56 60 57 61 ### Run Options ··· 65 69 66 70 1. Launch the app 67 71 2. Enter your Letta API key 68 - 3. Wait for Co to initialize (creates agent if needed) 72 + 3. Wait for co to initialize (creates agent if needed) 69 73 4. Start chatting! 70 74 71 75 ## Project Structure 72 76 73 77 ``` 74 - ion/ 75 - ├── App.tsx # Main Co application 76 - ├── CoLoginScreen.tsx # Login/authentication screen 78 + co/ 79 + ├── App.tsx # Main application 80 + ├── CoLoginScreen.tsx # Login/authentication 81 + ├── web-styles.css # Web-specific CSS for focus states and themes 77 82 ├── src/ 78 83 │ ├── api/ 79 84 │ │ └── lettaApi.ts # Letta API client 80 85 │ ├── components/ 81 - │ │ ├── MessageContent.tsx 82 - │ │ ├── ExpandableMessageContent.tsx 83 - │ │ ├── ToolCallItem.tsx 84 - │ │ └── LogoLoader.tsx 86 + │ │ ├── MessageContent.tsx # Markdown message rendering 87 + │ │ ├── ExpandableMessageContent.tsx # Collapsible long messages 88 + │ │ ├── ToolCallItem.tsx # Tool execution display 89 + │ │ └── LogoLoader.tsx # Loading animations 85 90 │ ├── types/ 86 91 │ │ └── letta.ts # TypeScript definitions 87 92 │ ├── utils/ 88 - │ │ ├── ionAgent.ts # Co agent creation logic 93 + │ │ ├── coAgent.ts # co agent creation logic 89 94 │ │ └── storage.ts # AsyncStorage wrapper 90 95 │ └── theme/ 91 - │ └── index.ts # Design system 96 + │ ├── index.ts # Theme system 97 + │ ├── colors.ts # Color palette 98 + │ └── typography.ts # Font definitions 92 99 ``` 93 100 94 - ## Key Files 101 + ## Key Features 102 + 103 + ### Smooth Token Streaming 104 + 105 + Messages stream at 50 FPS with a token buffer that releases 1-3 characters at a time for consistent, natural text appearance. A hollow circle indicator (○) appears at the end of streaming text. 106 + 107 + ### Animated Message Layout 95 108 96 - ### `src/utils/ionAgent.ts` 109 + When you send a message: 110 + 1. Message appears at the bottom 111 + 2. An animated spacer grows beneath it (400ms animation) 112 + 3. Your message smoothly rises to the top of the viewport 113 + 4. co's response fills the reserved space below 97 114 98 - Contains the `createCoAgent()` function that defines Co's system prompt, memory blocks, and configuration. This is where you can customize Co's personality and capabilities. 115 + This creates a clean reading experience where your message stays visible with room for the response. 99 116 100 - ### `src/api/lettaApi.ts` 117 + ### Theme Support 101 118 102 - Letta API client with: 103 - - `findAgentByTags()`: Find agent by tags 104 - - `findOrCreateCo()`: Get or create Co agent 105 - - `sendMessageStream()`: Stream messages from Co 106 - - `listAgentBlocks()`: View memory blocks 119 + Toggle between light and dark modes with inverted text input styling: 120 + - **Dark mode**: White background input with black text 121 + - **Light mode**: Black background input with white text 107 122 108 - ### `App.tsx` 123 + ### Memory Viewer 109 124 110 - Main application with: 111 - - Authentication flow 112 - - Co initialization 113 - - Chat interface 114 - - Memory viewer sidebar 115 - - Tool approval modals 125 + Access co's memory blocks through the sidebar to see what co has learned about you and how it's evolving its understanding over time. 116 126 117 - ## Customizing Co 127 + ## Customizing co 118 128 119 129 ### Modify Personality 120 130 121 - Edit `src/utils/ionAgent.ts` and update: 131 + Edit `src/utils/coAgent.ts` and update: 122 132 - System prompt 123 133 - Memory block initial values 124 134 - Available tools ··· 137 147 138 148 ### Change Model 139 149 140 - Update the `model` field in `createCoAgent()`: 150 + Update the `model` field in `findOrCreateCo()`: 141 151 142 152 ```typescript 143 153 model: 'openai/gpt-4.1', // or other supported models ··· 149 159 150 160 - **React Native** + **Expo**: Cross-platform framework 151 161 - **TypeScript**: Type safety 152 - - **Letta SDK**: AI agent framework 153 - - **AsyncStorage**: Persistent storage 162 + - **Letta SDK** (`@letta-ai/letta-client`): AI agent framework 163 + - **AsyncStorage/SecureStore**: Persistent storage 164 + - **React Native Markdown Display**: Markdown rendering 165 + - **Lexend Font**: Custom typography 154 166 155 167 ### Available Scripts 156 168 157 169 - `npm start` - Start Expo dev server 158 - - `npm run web` - Run in browser 170 + - `npm run web` - Run in browser (dev mode) 159 171 - `npm run android` - Run on Android 160 172 - `npm run ios` - Run on iOS 161 173 - `npx expo start -c` - Clear cache and restart 162 174 163 - ### Building for Production 175 + ### Production Build 176 + 177 + For better performance: 164 178 165 179 ```bash 166 - # Web build 167 - npm run build:web 180 + # Development with production optimizations 181 + npx expo start --web --no-dev --minify 168 182 169 - # Mobile builds (requires EAS CLI) 170 - npx eas build --platform all 183 + # Static production build 184 + npx expo export:web 185 + npx serve web-build 171 186 ``` 172 187 173 188 ## API Integration 174 189 175 - Co connects to Letta's API: 190 + co connects to Letta's API: 176 191 177 - - `GET /agents?tags=co-app` - Find Co agent 178 - - `POST /agents` - Create Co agent 192 + - `GET /agents?tags=co-app` - Find co agent 193 + - `POST /agents` - Create co agent 179 194 - `GET /agents/{id}/messages` - Load message history 180 195 - `POST /agents/{id}/messages/streaming` - Stream messages 181 196 - `GET /agents/{id}/blocks` - View memory blocks ··· 184 199 185 200 ### Agent Not Found 186 201 187 - If Co fails to initialize: 188 - 1. Check API token validity 202 + If co fails to initialize: 203 + 1. Check API token validity at letta.com 189 204 2. Verify network connection 190 205 3. Check console logs for errors 206 + 4. Try logging out and back in 191 207 192 208 ### Memory Blocks Not Loading 193 209 ··· 200 216 - Check network stability 201 217 - Verify streaming endpoint support 202 218 - Review console logs for chunk errors 219 + - Try clearing Expo cache: `npx expo start -c` 203 220 204 - ## Contributing 221 + ### Slow Performance 205 222 206 - Co is a reference implementation. To customize: 207 - 208 - 1. Fork the repository 209 - 2. Modify Co's configuration in `src/utils/ionAgent.ts` 210 - 3. Update UI components as needed 211 - 4. Test on multiple platforms 212 - 5. Submit pull request with clear description 223 + Run the app with production optimizations: 224 + ```bash 225 + npx expo start --web --no-dev --minify 226 + ``` 213 227 214 228 ## License 215 229 ··· 218 232 ## Resources 219 233 220 234 - [Letta Documentation](https://docs.letta.com) 235 + - [Letta LLMs.txt](https://docs.letta.com/llms.txt) 221 236 - [React Native Docs](https://reactnative.dev) 222 237 - [Expo Docs](https://docs.expo.dev)