{"id":35094458,"url":"https://github.com/officiallyutso/chronicle","last_synced_at":"2026-03-16T21:03:10.548Z","repository":{"id":302364501,"uuid":"1010711453","full_name":"officiallyutso/chronicle","owner":"officiallyutso","description":"Chronicle is a comprehensive, privacy-first activity tracking and analysis platform that leverages cutting-edge AI technologies to monitor, analyze, and narrativize your digital workflow.","archived":false,"fork":false,"pushed_at":"2025-11-22T10:41:32.000Z","size":11857,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-22T12:18:40.749Z","etag":null,"topics":["agentic-ai","browser-extension","chromadb","conversational-ai","express","langchain","local-ai","ollama","react-electron","semantic-search","unity-package","vscode-extension","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/officiallyutso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-29T16:42:19.000Z","updated_at":"2025-11-22T10:41:35.000Z","dependencies_parsed_at":"2025-07-02T02:25:14.216Z","dependency_job_id":"36d0afd9-538c-4087-9b4f-89bac4a04450","html_url":"https://github.com/officiallyutso/chronicle","commit_stats":null,"previous_names":["officiallyutso/chronicle"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/officiallyutso/chronicle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/officiallyutso%2Fchronicle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/officiallyutso%2Fchronicle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/officiallyutso%2Fchronicle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/officiallyutso%2Fchronicle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/officiallyutso","download_url":"https://codeload.github.com/officiallyutso/chronicle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/officiallyutso%2Fchronicle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28080215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-27T02:00:05.897Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","browser-extension","chromadb","conversational-ai","express","langchain","local-ai","ollama","react-electron","semantic-search","unity-package","vscode-extension","websocket"],"created_at":"2025-12-27T15:05:14.635Z","updated_at":"2025-12-27T15:07:04.685Z","avatar_url":"https://github.com/officiallyutso.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/b50924f3-6e28-440f-ae36-94f154cd27a7\" alt=\"Chronicle AI Logo\" width=\"100\"\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n   \n![Chronicle Logo](https://img.shields.io/badge/Chronicle-AI%20Tracking%20%26%20Analysis-blue?style=for-the-badge\u0026logo=brain\u0026logoColor=white)\n\n[![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://python.org)\n[![Node.js](https://img.shields.io/badge/Electron-339933?style=for-the-badge\u0026logo=nodedotjs\u0026logoColor=white)](https://nodejs.org)\n[![LangChain](https://img.shields.io/badge/LangChain-121212?style=for-the-badge\u0026logo=chainlink\u0026logoColor=white)](https://langchain.com)\n[![ChromaDB](https://img.shields.io/badge/ChromaDB-FF6B6B?style=for-the-badge\u0026logo=database\u0026logoColor=white)](https://chromadb.com)\n[![Ollama](https://img.shields.io/badge/Ollama-000000?style=for-the-badge\u0026logo=llama\u0026logoColor=white)](https://ollama.ai)\n[![React](https://img.shields.io/badge/React-61DAFB?style=for-the-badge\u0026logo=react\u0026logoColor=black)](https://react.dev)\n[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)\n[![Platform](https://img.shields.io/badge/Platform-Cross%20Platform-lightgrey?style=for-the-badge)](https://github.com/officiallyutso/chronicle)\n\n**Revolutionizing Digital Workflow Intelligence with AI-Powered Activity Analysis**\n\n*Chronicle is a comprehensive, privacy-first activity tracking and analysis platform that leverages cutting-edge AI technologies to monitor, analyze, and narrativize your digital workflow. Built with modern technologies including LangChain, Ollama, ChromaDB, and React, Chronicle provides intelligent insights into your development activities while keeping all data completely local and secure.*\n\u003c/div\u003e\n\n---\n\n# Table of Contents\n\n\u003cdetails\u003e\n\u003csummary\u003eSystem Architecture\u003c/summary\u003e\n\n- [Overview](#overview)\n- [Technology Stack](#technology-stack)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCore Components\u003c/summary\u003e\n\n- [VS Code Extension](#vs-code-extension)\n- [Browser Extension](#browser-extension)\n- [System Monitor](#system-monitor)\n- [Desktop Application](#desktop-application)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAI \u0026 Vector Database\u003c/summary\u003e\n\n- [Agentic AI System](#agentic-ai-system)\n- [Vector Database Integration](#vector-database-integration)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstallation \u0026 Setup\u003c/summary\u003e\n\n- [Prerequisites](#prerequisites)\n- [Step-by-Step Installation](#step-by-step-installation)\n- [Advanced Configuration](#advanced-configuration)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAPI Reference\u003c/summary\u003e\n\n- [Core Backend Endpoints](#core-backend-endpoints)\n- [WebSocket Events](#websocket-events)\n- [Extension APIs](#extension-apis)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePerformance \u0026 Security\u003c/summary\u003e\n\n- [Performance Optimization](#performance-optimization)\n- [Security \u0026 Privacy](#security--privacy)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDevelopment\u003c/summary\u003e\n\n- [Development Setup](#development-setup)\n- [Project Structure](#project-structure)\n- [Troubleshooting](#troubleshooting)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFuture Roadmap\u003c/summary\u003e\n\n- [Future Roadmap](#future-roadmap)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLicense \u0026 Acknowledgments\u003c/summary\u003e\n\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n\u003c/details\u003e\n\n---\n\n## System Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph \"User Environment\"\n        VSCode[VS Code Extension]\n        Browser[Browser Extension]\n        Desktop[Desktop App - Electron]\n        System[System Monitor]\n    end\n    \n    subgraph \"Core Backend Microservices\"\n        Backend[Express Backend Server]\n        Vector[ChromaDB Vector Store]\n        AI[Ollama + LangChain]\n        Agent[Enhanced Agent Service]\n    end\n    \n    subgraph \"AI Components\"\n        Embeddings[Nomic Embeddings]\n        Chat[Conversational AI]\n        Narrative[Story Generator]\n        Memory[Context Memory]\n    end\n    \n    subgraph \"Data Layer\"\n        ChromaDB[(ChromaDB)]\n        LocalFiles[(Local Files)]\n        VectorData[(Vector Embeddings)]\n    end\n    \n    VSCode --\u003e Backend\n    Browser --\u003e Backend\n    System --\u003e Backend\n    Desktop --\u003e Backend\n    \n    Backend --\u003e Vector\n    Backend --\u003e AI\n    Backend --\u003e Agent\n    \n    AI --\u003e Embeddings\n    AI --\u003e Chat\n    AI --\u003e Narrative\n    AI --\u003e Memory\n    \n    Vector --\u003e ChromaDB\n    Agent --\u003e VectorData\n    Backend --\u003e LocalFiles\n    \n    ChromaDB --\u003e VectorData\n```\n\n---\n\n## Technology Stack\n\n### Core Technologies\n| Component | Technology | Version | Purpose |\n|-----------|------------|---------|---------|\n| **Frontend** | React 19 + TypeScript | 19.1.0 | Modern UI with type safety |\n| **Desktop App** | Electron | 37.1.0 | Cross-platform desktop application |\n| **Backend** | Express.js + TypeScript | 4.18.2 | RESTful API and WebSocket server |\n| **AI Framework** | LangChain | 0.3.57 | Agentic AI and language model integration |\n| **Vector Database** | ChromaDB | 3.0.6 | Semantic search and embeddings storage |\n| **Embeddings** | Nomic-embed-text | Latest | High-quality text embeddings |\n| **LLM** | Ollama + Llama3 | Latest | Local language model inference |\n| **Build Tool** | Vite | 7.0.0 | Fast development and build system |\n\n---\n\n## Activity Tracker Features\n\n| Description | Screenshot |\n|-------------|------------|\n| **Dashboard** - Main interface showing overview of your daily activities and statistics | \u003cimg src=\"https://github.com/user-attachments/assets/a0ef5a2e-43c0-4d9e-bd3e-8e6d9ac56179\" width=\"600\"\u003e |\n| **Activity Panel** - View and manage your tracked activities with detailed information | \u003cimg src=\"https://github.com/user-attachments/assets/f6612f23-5af7-4da8-9adc-38cd34997d69\" width=\"600\"\u003e |\n| **Activity Details** - Detailed view of individual activities with time tracking and metadata | \u003cimg src=\"https://github.com/user-attachments/assets/9a69dbdf-9b97-42cb-aeca-12a28edda50e\" width=\"600\"\u003e |\n| **Activity Sorting** - Sort and filter activities by different criteria for better organization | \u003cimg src=\"https://github.com/user-attachments/assets/1a8e088d-416d-469f-82ce-9b30c406c1cc\" width=\"600\"\u003e |\n| **Activity Based Narrative - Tone Selection** - Choose the tone and style for generating narratives from your activities | \u003cimg src=\"https://github.com/user-attachments/assets/ddbedafd-e2a5-4ab6-a6d9-401a310bf416\" width=\"600\"\u003e |\n| **Activity Based Narrative - Story Generation** - Generate compelling stories and narratives based on your tracked activities | \u003cimg src=\"https://github.com/user-attachments/assets/1c8a566e-f1f9-47a5-a5c4-f7e212ec41ec\" width=\"600\"\u003e |\n| **Activity Based Narrative - Achievement Summary** - View achievements and milestones based on your activity patterns | \u003cimg src=\"https://github.com/user-attachments/assets/44457de6-0171-40ea-a50b-1b425b57c0d0\" width=\"600\"\u003e |\n| **Agentic AI Context Chat** - Chat with AI about your daily activities and get insights from your data | \u003cimg src=\"https://github.com/user-attachments/assets/1f74b766-c82f-4084-8ac6-13e77f25ee02\" width=\"600\"\u003e |\n| **AI Chat Interface** - Interactive chat interface for discussing your activities with AI assistance | \u003cimg src=\"https://github.com/user-attachments/assets/ce19d11a-67a0-4e3c-8776-8d9c8248f2af\" width=\"600\"\u003e |\n| **AI Data Context** - AI shows the specific data it's referencing when providing insights about your activities | \u003cimg src=\"https://github.com/user-attachments/assets/398628eb-7958-4ea3-9193-70ea832cbe2a\" width=\"600\"\u003e |\n| **Project AI - VS Code Integration** - Automatically detects and connects to your VS Code projects for enhanced tracking | \u003cimg src=\"https://github.com/user-attachments/assets/3f8622b5-19d7-47e4-9af5-af5800f6d1e1\" width=\"600\"\u003e |\n| **Project AI - Project Summary** - Get comprehensive summaries of your projects including structure and progress | \u003cimg src=\"https://github.com/user-attachments/assets/5d03869f-e81e-43f5-b319-a813a5eed191\" width=\"600\"\u003e |\n| **Project AI - File Structure** - View detailed file structure and organization of your projects | \u003cimg src=\"https://github.com/user-attachments/assets/ad031c26-c54f-48f6-862b-5144cf821735\" width=\"600\"\u003e |\n| **Project AI - README Generation** - Generate perfect README files automatically based on your project structure and activity | \u003cimg src=\"https://github.com/user-attachments/assets/c798dcd0-bded-4eae-b6cc-99970070f2ba\" width=\"600\"\u003e |\n| **Settings \u0026 Clear Data** - Manage application settings and clear your data when needed | \u003cimg src=\"https://github.com/user-attachments/assets/8ac70688-c174-4c4d-aba8-30f78fd336bb\" width=\"600\"\u003e |\n| **Browser Extension** - Track your web browsing activities and integrate with the main application | \u003cimg src=\"https://github.com/user-attachments/assets/faab72a9-2220-46ea-9ccc-f47851f5eebd\" height=\"400\"\u003e |\n| **Browser Extension Integration** - Seamless integration between browser extension and main application | \u003cimg src=\"https://github.com/user-attachments/assets/46cf3aa5-72b7-4fa7-9653-a88467899b20\" height=\"400\"\u003e |\n| **VS Code Extension - Available Commands** - View all available commands and features within the VS Code extension | \u003cimg src=\"https://github.com/user-attachments/assets/56103246-74ca-4f0e-9e43-0cd6fcccdff3\" width=\"600\"\u003e |\n| **VS Code Extension - Activity Log** - Track your coding activities directly within VS Code with detailed logging | \u003cimg src=\"https://github.com/user-attachments/assets/8bf979d9-d57e-452c-ba78-901ae23194fd\" width=\"600\"\u003e |\n| **VS Code Extension - Project Summary** - Get project summaries and insights directly within your VS Code workspace | \u003cimg src=\"https://github.com/user-attachments/assets/fc4b20ac-f2d9-4937-8027-a7cfc145b0f5\" width=\"600\"\u003e |\n| **UNITY - AI package** - Package to generate npc characters - Agentic AI  | \u003cimg src=\"https://github.com/user-attachments/assets/d39735f4-857b-472a-a105-7d6f1f214634\" width=\"600\"\u003e |\n| **UNITY - NPC AI** - Package to generate scriptable npc characters - Agentic AI  | \u003cimg src=\"https://github.com/user-attachments/assets/476603d0-20b9-4986-8971-1a9b77ec9799\" width=\"600\"\u003e |\n| **UNITY - In Game Demo** - Example of how the package can be used to make AI games with real time contextual decision making  | \u003cimg src=\"https://github.com/user-attachments/assets/77d7975f-d199-458a-be97-e37f2ab22fb8\" width=\"600\"\u003e |\n\n---\n\n\n## VS Code Extension Architecture\n\n### Extension Components\n\n```mermaid\n\ngraph LR\n\n    subgraph \"VS Code Extension\"\n        ExtMain[extension.ts]\n        Summarizer[summarizer.ts]\n        Commands[Command Handlers]\n        FileWatcher[File System Watcher]\n    end\n    \n    subgraph \"VS Code API\"\n        Workspace[Workspace API]\n        TextDoc[TextDocument API]\n        Commands2[Commands API]\n        FileSystem[FileSystem API]\n    end\n    \n    subgraph \"Backend Integration\"\n        ProjectAPI[Project API]\n        OllamaAPI[Ollama API]\n        ChromaStore[ChromaDB Storage]\n    end\n    \n    ExtMain --\u003e Commands\n    ExtMain --\u003e FileWatcher\n    ExtMain --\u003e Summarizer\n    \n    Commands --\u003e Workspace\n    FileWatcher --\u003e FileSystem\n    Summarizer --\u003e TextDoc\n    \n    Summarizer --\u003e OllamaAPI\n    ExtMain --\u003e ProjectAPI\n    ProjectAPI --\u003e ChromaStore\n```\n\n\n### Core Features\n\n**File Activity Tracking**\n- Monitors file open/close/save operations\n- Tracks file modifications and creations\n- Captures project-level context and metadata\n- Filters development-relevant file types\n\n**Intelligent Project Analysis**\n- Generates comprehensive project summaries using Ollama\n- Analyzes folder structures and file relationships\n- Creates contextual file summaries with AI\n- Exports structured project data to backend\n\n**Command Integration**\n```typescript\n// Key VS Code commands implemented\n'chronicle.activateChronicle'     // Start tracking\n'chronicle.deactivateChronicle'   // Stop tracking\n'chronicle.summarizeProject'      // Full project analysis\n'chronicle.summarizeCurrentFile'  // Single file summary\n'chronicle.summarizeCurrentFolder' // Folder analysis\n'chronicle.openLog'              // View activity log\n```\n\n\n### Data Flow Architecture\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant VSCode\n    participant Extension\n    participant Ollama\n    participant Backend\n    participant ChromaDB\n    \n    User-\u003e\u003eVSCode: Opens/Edits File\n    VSCode-\u003e\u003eExtension: File Event\n    Extension-\u003e\u003eExtension: Log Activity\n    User-\u003e\u003eExtension: Summarize Project\n    Extension-\u003e\u003eOllama: Generate Summary\n    Ollama-\u003e\u003eExtension: AI Summary\n    Extension-\u003e\u003eBackend: Send Project Data\n    Backend-\u003e\u003eChromaDB: Store Embeddings\n    ChromaDB-\u003e\u003eBackend: Confirm Storage\n    Backend-\u003e\u003eExtension: Success Response\n    Extension-\u003e\u003eVSCode: Show Results\n```\n\n---\n\n## Browser Extension Architecture\n\n### Extension Components\n\n```mermaid\ngraph TB\n    subgraph \"Browser Extension\"\n        Background[background.jsService Worker]\n        Content[content.jsContent Script]\n        Popup[popup.html/jsUser Interface]\n        Manifest[manifest.jsonConfiguration]\n    end\n    \n    subgraph \"Browser APIs\"\n        Tabs[Tabs API]\n        History[History API]\n        Storage[Storage API]\n        WebNav[WebNavigation API]\n    end\n    \n    subgraph \"Web Pages\"\n        SearchEngines[Search Engines]\n        Websites[Regular Websites]\n        SPA[Single Page Apps]\n    end\n    \n    subgraph \"Backend\"\n        BrowserAPI[Browser Events API]\n        EventStore[Event Storage]\n    end\n    \n    Background --\u003e Tabs\n    Background --\u003e History\n    Background --\u003e Storage\n    Content --\u003e SearchEngines\n    Content --\u003e Websites\n    Content --\u003e SPA\n    \n    Background --\u003e BrowserAPI\n    BrowserAPI --\u003e EventStore\n    \n    Popup --\u003e Background\n    Content --\u003e Background\n```\n\n### Tracking Capabilities\n\n**Search Activity Monitoring**\n- Detects searches across major search engines (Google, Bing, DuckDuckGo, Yahoo)\n- Extracts search queries and tracks search result clicks\n- Monitors search result positions and engagement\n- Tracks search session duration and patterns\n\n**Website Activity Tracking**\n- Monitors website visits and session durations\n- Tracks tab switching and focus events\n- Captures page titles and domain information\n- Detects single-page application navigation\n\n**Engagement Analytics**\n- Scroll depth tracking for content engagement\n- Page visibility change detection\n- Click pattern analysis\n- Session time measurement\n\n### Search Engine Integration\n\n```mermaid\ngraph LR\n    subgraph \"Search Engines\"\n        Google[Google Search]\n        Bing[Bing Search]\n        Duck[DuckDuckGo]\n        Yahoo[Yahoo Search]\n    end\n    \n    subgraph \"Detection Logic\"\n        URLParser[URL Parser]\n        QueryExtractor[Query Extractor]\n        ResultDetector[Result Detector]\n    end\n    \n    subgraph \"Event Types\"\n        SearchPerformed[Search Performed]\n        ResultClicked[Result Clicked]\n        EngineVisited[Engine Visited]\n    end\n    \n    Google --\u003e URLParser\n    Bing --\u003e URLParser\n    Duck --\u003e URLParser\n    Yahoo --\u003e URLParser\n    \n    URLParser --\u003e QueryExtractor\n    QueryExtractor --\u003e ResultDetector\n    \n    ResultDetector --\u003e SearchPerformed\n    ResultDetector --\u003e ResultClicked\n    ResultDetector --\u003e EngineVisited\n```\n\n---\n\n## System Monitor Microservice\n\n### Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph \"System Monitor Service\"\n        Monitor[SystemMonitor Class]\n        AppTracker[Application Tracker]\n        FileWatcher[File System Watcher]\n        TerminalMonitor[Terminal Monitor]\n        MetricsCollector[System Metrics]\n    end\n    \n    subgraph \"OS Integration\"\n        ProcessAPI[Process APIs]\n        FileSystemAPI[File System APIs]\n        HistoryFiles[Shell History Files]\n        SystemAPIs[System APIs]\n    end\n    \n    subgraph \"Data Processing\"\n        EventEmitter[Event Emitter]\n        DataFilter[Data Filtering]\n        ContextEnricher[Context Enricher]\n    end\n    \n    subgraph \"Output\"\n        WebSocket[WebSocket Events]\n        APIEndpoints[REST API]\n        VectorStore[Vector Storage]\n    end\n    \n    Monitor --\u003e AppTracker\n    Monitor --\u003e FileWatcher\n    Monitor --\u003e TerminalMonitor\n    Monitor --\u003e MetricsCollector\n    \n    AppTracker --\u003e ProcessAPI\n    FileWatcher --\u003e FileSystemAPI\n    TerminalMonitor --\u003e HistoryFiles\n    MetricsCollector --\u003e SystemAPIs\n    \n    Monitor --\u003e EventEmitter\n    EventEmitter --\u003e DataFilter\n    DataFilter --\u003e ContextEnricher\n    \n    ContextEnricher --\u003e WebSocket\n    ContextEnricher --\u003e APIEndpoints\n    ContextEnricher --\u003e VectorStore\n```\n\n### Cross-Platform Monitoring\n\n**Application Tracking**\n```typescript\n// Platform-specific application monitoring\nswitch (this.platform) {\n  case 'darwin':\n    // macOS: ps -eo comm\n    const { stdout } = await execAsync('ps -eo comm | grep -v \"^COMMAND\"');\n    break;\n  case 'win32':\n    // Windows: tasklist /fo csv\n    const { stdout } = await execAsync('tasklist /fo csv');\n    break;\n  case 'linux':\n    // Linux: ps -eo comm --no-headers\n    const { stdout } = await execAsync('ps -eo comm --no-headers');\n    break;\n}\n```\n\n**Terminal Command Monitoring**\n- Bash history file monitoring (`~/.bash_history`)\n- Zsh history tracking (`~/.zsh_history`)\n- PowerShell history on Windows\n- Real-time process monitoring for active terminals\n- Command context detection (git, npm, python, etc.)\n\n**File System Monitoring**\n- Recursive directory watching with exclusion filters\n- Development file type filtering (.js, .ts, .py, .java, etc.)\n- Project context detection and classification\n- Change type detection (create, modify, delete)\n\n### Event Processing Pipeline\n\n```mermaid\nflowchart TD\n    A[Raw System Event] --\u003e B{Event Type}\n    B --\u003e|Application| C[App Event Processor]\n    B --\u003e|File System| D[File Event Processor]\n    B --\u003e|Terminal| E[Terminal Event Processor]\n    B --\u003e|System| F[System Event Processor]\n    \n    C --\u003e G[Context Enrichment]\n    D --\u003e G\n    E --\u003e G\n    F --\u003e G\n    \n    G --\u003e H[Data Validation]\n    H --\u003e I[Event Emission]\n    I --\u003e J[WebSocket Broadcast]\n    I --\u003e K[Vector Storage]\n    I --\u003e L[Real-time Dashboard]\n```\n\n---\n\n## Agentic AI System\n\n### Enhanced Agent Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Enhanced Agent Service\"\n        Agent[EnhancedAgentService]\n        Memory[BufferMemory]\n        Chain[ConversationChain]\n        Tools[Analysis Tools]\n    end\n    \n    subgraph \"LangChain Components\"\n        LLM[ChatOllama]\n        Prompt[ChatPromptTemplate]\n        MemoryBuffer[Memory Buffer]\n    end\n    \n    subgraph \"Custom Tools\"\n        ActivityTool[ActivityAnalysisTool]\n        MemoryTool[ConversationMemoryTool]\n        VectorTool[VectorSearchTool]\n    end\n    \n    subgraph \"Data Sources\"\n        VectorDB[ChromaDB]\n        EventStream[Activity Events]\n        Context[Conversation Context]\n    end\n    \n    Agent --\u003e Memory\n    Agent --\u003e Chain\n    Agent --\u003e Tools\n    \n    Chain --\u003e LLM\n    Chain --\u003e Prompt\n    Memory --\u003e MemoryBuffer\n    \n    Tools --\u003e ActivityTool\n    Tools --\u003e MemoryTool\n    Tools --\u003e VectorTool\n    \n    ActivityTool --\u003e VectorDB\n    ActivityTool --\u003e EventStream\n    MemoryTool --\u003e Context\n    VectorTool --\u003e VectorDB\n```\n\n### AI Agent Capabilities\n\n**Conversational Intelligence**\n- Persistent conversation memory across sessions\n- Context-aware response generation\n- Activity data integration in responses\n- Natural language query processing\n\n**Activity Analysis Tools**\n```typescript\nclass ActivityAnalysisTool extends Tool {\n  name = 'activity_analysis';\n  description = 'Analyze and search through user activity data';\n  \n  async _call(input: string): Promise {\n    const events = await this.vectorStore.searchSimilarActivities(input, 50);\n    const analysis = this.analyzeEvents(events);\n    return JSON.stringify(analysis);\n  }\n}\n```\n\n**Data Processing Pipeline**\n- Event categorization and grouping\n- Time-based analysis and patterns\n- Application usage statistics\n- File modification tracking\n- Terminal command analysis\n\n### Prompt Engineering\n\n```mermaid\ngraph LR\n    subgraph \"Prompt Components\"\n        SystemPrompt[System Instructions]\n        ActivityData[Activity Data Context]\n        ConversationHistory[Conversation History]\n        UserQuery[User Query]\n    end\n    \n    subgraph \"Processing\"\n        PromptTemplate[Prompt Template]\n        ContextInjection[Context Injection]\n        ResponseGeneration[Response Generation]\n    end\n    \n    subgraph \"Output\"\n        StructuredResponse[Structured Response]\n        AnalysisData[Analysis Data]\n        ConversationUpdate[Memory Update]\n    end\n    \n    SystemPrompt --\u003e PromptTemplate\n    ActivityData --\u003e ContextInjection\n    ConversationHistory --\u003e ContextInjection\n    UserQuery --\u003e PromptTemplate\n    \n    PromptTemplate --\u003e ResponseGeneration\n    ContextInjection --\u003e ResponseGeneration\n    \n    ResponseGeneration --\u003e StructuredResponse\n    ResponseGeneration --\u003e AnalysisData\n    ResponseGeneration --\u003e ConversationUpdate\n```\n\n---\n\n## Vector Database Integration\n\n### ChromaDB Architecture\n\n```mermaid\ngraph TB\n    subgraph \"ChromaDB Service\"\n        ChromaServer[ChromaDB Server]\n        Collections[Collections]\n        Embeddings[Embedding Engine]\n        QueryEngine[Query Engine]\n    end\n    \n    subgraph \"Data Types\"\n        ActivityEvents[Activity Events]\n        ProjectSummaries[Project Summaries]\n        ConversationHistory[Chat History]\n        FileContents[File Contents]\n    end\n    \n    subgraph \"Embedding Models\"\n        NomicEmbed[Nomic-embed-text]\n        OllamaEmbed[Ollama Embeddings]\n    end\n    \n    subgraph \"Query Types\"\n        SemanticSearch[Semantic Search]\n        SimilaritySearch[Similarity Search]\n        ContextRetrieval[Context Retrieval]\n    end\n    \n    ActivityEvents --\u003e ChromaServer\n    ProjectSummaries --\u003e ChromaServer\n    ConversationHistory --\u003e ChromaServer\n    FileContents --\u003e ChromaServer\n    \n    ChromaServer --\u003e Collections\n    Collections --\u003e Embeddings\n    Embeddings --\u003e NomicEmbed\n    Embeddings --\u003e OllamaEmbed\n    \n    Collections --\u003e QueryEngine\n    QueryEngine --\u003e SemanticSearch\n    QueryEngine --\u003e SimilaritySearch\n    QueryEngine --\u003e ContextRetrieval\n```\n\n### Vector Storage Implementation\n\n**Event Vectorization**\n```typescript\nasync storeActivityEvent(event: ActivityEvent): Promise {\n  const document = new Document({\n    pageContent: this.eventToText(event),\n    metadata: {\n      id: event.id,\n      type: event.type,\n      timestamp: event.timestamp,\n      category: event.category,\n      data: JSON.stringify(event.data),\n    },\n  });\n  \n  await this.chroma!.addDocuments([document], { ids: [event.id] });\n}\n```\n\n**Semantic Search Capabilities**\n- Natural language activity queries\n- Time-based activity retrieval\n- Context-aware similarity matching\n- Multi-modal data correlation\n\n---\n\n## Desktop Application Architecture\n\n### Electron Frontend Structure\n\n```mermaid\ngraph TB\n    subgraph \"Electron App\"\n        Main[Main Process]\n        Renderer[Renderer Process]\n        IPC[IPC Communication]\n    end\n    \n    subgraph \"React Frontend\"\n        App[App.tsx]\n        Dashboard[Dashboard Component]\n        ActivityFeed[Activity Feed]\n        ChatPanel[Chat Panel]\n        NarrativePanel[Narrative Panel]\n        Projects[Projects Component]\n        Settings[Settings Panel]\n    end\n    \n    subgraph \"Services\"\n        ApiService[API Service]\n        AgentService[Agent API Service]\n        ChatService[Chat Service]\n        OllamaService[Ollama Service]\n        SystemTracker[System Tracker]\n    end\n    \n    subgraph \"Backend Communication\"\n        WebSocket[WebSocket Client]\n        RestAPI[REST API Client]\n        EventStream[Event Stream]\n    end\n    \n    Main --\u003e Renderer\n    Renderer --\u003e IPC\n    \n    Renderer --\u003e App\n    App --\u003e Dashboard\n    App --\u003e ActivityFeed\n    App --\u003e ChatPanel\n    App --\u003e NarrativePanel\n    App --\u003e Projects\n    App --\u003e Settings\n    \n    App --\u003e ApiService\n    App --\u003e AgentService\n    App --\u003e ChatService\n    App --\u003e OllamaService\n    App --\u003e SystemTracker\n    \n    ApiService --\u003e WebSocket\n    ApiService --\u003e RestAPI\n    WebSocket --\u003e EventStream\n```\n\n### Component Architecture\n\n**Dashboard Component**\n- Real-time activity statistics\n- Session tracking and metrics\n- Recent activity feed\n- Achievement display system\n\n**Chat Panel Integration**\n```typescript\nconst handleSendMessage = async () =\u003e {\n  const response: ChatResponse = await chatService.sendMessage(inputMessage);\n  const assistantMessage: ChatMessage = {\n    id: `assistant_${Date.now()}`,\n    type: 'assistant',\n    content: response.output,\n    timestamp: Date.now(),\n    analysis: response.analysis\n  };\n  setMessages(prev =\u003e [...prev, assistantMessage]);\n};\n```\n\n**Narrative Generation System**\n- Multiple tone options (casual, professional, gamified, technical)\n- Format variations (story, log, achievements, summary)\n- Export capabilities (JSON, Markdown, clipboard)\n- Achievement system integration\n\n---\n\n## Data Flow Architecture\n\n### Real-time Event Processing\n\n```mermaid\nsequenceDiagram\n    participant Extensions as Extensions\n    participant Backend as Backend Server\n    participant Vector as Vector Store\n    participant AI as AI Agent\n    participant Frontend as Desktop App\n    \n    Extensions-\u003e\u003eBackend: Activity Event\n    Backend-\u003e\u003eVector: Store Event Embedding\n    Backend-\u003e\u003eFrontend: WebSocket Broadcast\n    Frontend-\u003e\u003eFrontend: Update UI\n    \n    Frontend-\u003e\u003eBackend: User Query\n    Backend-\u003e\u003eVector: Semantic Search\n    Vector-\u003e\u003eBackend: Relevant Events\n    Backend-\u003e\u003eAI: Generate Response\n    AI-\u003e\u003eBackend: AI Response\n    Backend-\u003e\u003eFrontend: Response + Analysis\n```\n\n### Project Analysis Workflow\n\n```mermaid\nflowchart TD\n    A[VS Code Project] --\u003e B[Extension Analysis]\n    B --\u003e C[File Summarization]\n    C --\u003e D[Folder Analysis]\n    D --\u003e E[Project Summary Generation]\n    E --\u003e F[Backend API Call]\n    F --\u003e G[Vector Storage]\n    G --\u003e H[Frontend Display]\n    \n    I[User Request] --\u003e J[README Generation]\n    J --\u003e K[AI Processing]\n    K --\u003e L[Structured Output]\n    L --\u003e M[Export Options]\n```\n\n---\n\n## Installation \u0026 Setup\n\n### Prerequisites\n\n| Requirement | Version | Purpose |\n|-------------|---------|---------|\n| Node.js | ≥18.0.0 | Runtime environment |\n| npm | ≥8.0.0 | Package management |\n| Python | ≥3.8 | Backend AI services |\n| Ollama | Latest | Local AI model serving |\n| ChromaDB | ≥0.5.15 | Vector database |\n\n### Step-by-Step Installation\n\n**1. Install Ollama and Models**\n```bash\n# Install Ollama (macOS/Linux)\ncurl -fsSL https://ollama.ai/install.sh | sh\n\n# Windows: Download from https://ollama.ai/download\n\n# Install required models\nollama pull llama3\nollama pull nomic-embed-text\n```\n\n**2. Clone and Setup Main Application**\n```bash\n# Clone the repository\ngit clone https://github.com/officiallyutso/chronicle.git\ncd chronicle\n\n# Install dependencies\nnpm install\n\n# Run TypeScript for Electron\nnpm run dev:all\n```\n\n**3. Setup Backend MicroServices**\n```bash\n# Navigate to backend directory\ncd backend\n\n# Install backend dependencies\nnpm install\n\n# Start the backend server\nnpm run dev\n```\n\n**4. Setup ChromaDB Vector Database**\n```bash\n# Install ChromaDB (in root dir)\npip install chromadb\n\n# Start ChromaDB server\nchroma run --host 0.0.0.0 --port 8000 --path ../chronicle_data\n```\n\n**5. Install VS Code Extension**\n```bash\n# Navigate to VS Code extension directory\ncd vs-code-extension\n\n# Install dependencies\nnpm install\n\n# Compile the extension\nnpm run compile\n\n# Install in VS Code\n# Method 1: Press F5 to run in development mode (preferred)\n# Method 2: Package and install\nvsce package\ncode --install-extension chronicle-*.vsix\n```\n\n**6. Install Browser Extension**\n\n**Chrome/Edge:**\n1. Open `chrome://extensions/`\n2. Enable \"Developer mode\"\n3. Click \"Load unpacked\"\n4. Select the `chronicle-browser-extension` folder\n\n**Firefox:**\n1. Open `about:debugging`\n2. Click \"This Firefox\"\n3. Click \"Load Temporary Add-on\"\n4. Select `manifest.json` from the extension folder\n\n**7. Start the Complete System**\n```bash\n# Terminal 1: Start ChromaDB\nchroma run --host 0.0.0.0 --port 8000 --path ./chronicle_data\n\n# Terminal 2: Start Backend\ncd backend \u0026\u0026 npm run dev\n\n# Terminal 3: Start Desktop App\nnpm run dev:all\n```\n\n---\n\n## Advanced Configuration\n\n### Environment Variables\n```bash\n# Backend Configuration (.env)\nPORT=3001\nOLLAMA_BASE_URL=http://localhost:11434\nCHROMA_URL=http://localhost:8000\nEMBEDDING_MODEL=nomic-embed-text\nCHAT_MODEL=llama3\n```\n\n### VS Code Extension Settings\n```json\n{\n  \"chronicle.autoSummarize\": true,\n  \"chronicle.trackFileChanges\": true,\n  \"chronicle.backendUrl\": \"http://localhost:3001\",\n  \"chronicle.maxFileSummaryLines\": 80\n}\n```\n\n### Browser Extension Configuration\n```javascript\n// Extension settings\nconst BACKEND_URL = 'http://localhost:3001';\nconst SEARCH_ENGINES = {\n  'google.com': 'Google',\n  'bing.com': 'Bing',\n  'duckduckgo.com': 'DuckDuckGo'\n};\n```\n\n---\n\n## API Reference\n\n### Core Backend Endpoints\n\n| Endpoint | Method | Purpose | Request Body |\n|----------|--------|---------|--------------|\n| `/api/events` | GET | Retrieve activity events | Query params: type, limit, startTime, endTime |\n| `/api/stats` | GET | Get session statistics | None |\n| `/api/ai/chat` | POST | Chat with AI agent | `{ message: string }` |\n| `/api/ai/narrative` | POST | Generate activity narrative | `{ style: NarrativeStyle }` |\n| `/api/projects` | GET/POST | Project management | Project data object |\n| `/api/projects/:id/readme` | POST | Generate README | None |\n| `/api/tracking/start` | POST | Start activity tracking | None |\n| `/api/tracking/stop` | POST | Stop activity tracking | None |\n\n### WebSocket Events\n\n```typescript\ninterface WebSocketMessage {\n  type: 'INITIAL_EVENTS' | 'NEW_EVENT';\n  data: ActivityEvent | ActivityEvent[];\n}\n\ninterface ActivityEvent {\n  id: string;\n  timestamp: number;\n  type: ActivityType;\n  data: any;\n  category: string;\n}\n```\n\n### Extension APIs\n\n**VS Code Extension Commands**\n```typescript\n// Available commands\n'chronicle.activateChronicle'      // Start tracking\n'chronicle.deactivateChronicle'    // Stop tracking\n'chronicle.summarizeProject'       // Analyze entire project\n'chronicle.summarizeCurrentFile'   // Analyze current file\n'chronicle.summarizeCurrentFolder' // Analyze current folder\n'chronicle.openLog'               // View activity log\n```\n\n**Browser Extension Messages**\n```javascript\n// Message types\nchrome.runtime.sendMessage({\n  type: 'SEARCH_RESULT_CLICK',\n  url: string,\n  title: string,\n  searchEngine: string,\n  searchQuery: string,\n  position: number\n});\n```\n\n---\n\n## Performance Optimization\n\n### System Requirements\n- **RAM**: Minimum 8GB (16GB recommended for large projects)\n- **Storage**: 2GB free space for models and data\n- **CPU**: Modern multi-core processor for AI inference\n- **Network**: Local network for service communication\n\n### Optimization Strategies\n\n**Vector Database Optimization**\n```typescript\n// Batch processing for better performance\nconst batchSize = 100;\nconst eventBatches = chunk(events, batchSize);\nfor (const batch of eventBatches) {\n  await vectorStore.addDocuments(batch);\n}\n```\n\n**Memory Management**\n- Conversation history limited to last 6 messages\n- Event cleanup after 10 minutes of inactivity\n- Automatic garbage collection for old embeddings\n\n**AI Model Optimization**\n- Use quantized models for better performance\n- Implement response caching for common queries\n- Batch similar requests for efficiency\n\n---\n\n## Security \u0026 Privacy\n\n### Data Protection\n- **100% Local Processing**: All data remains on your machine\n- **No Cloud Dependencies**: Complete offline functionality\n- **Encrypted Storage**: Vector embeddings provide data abstraction\n- **User Control**: Full data export and deletion capabilities\n\n### Security Features\n- **Sandboxed Extensions**: Browser and VS Code extensions run in isolated environments\n- **API Validation**: Input sanitization and validation\n- **Local Inference**: AI processing entirely on local machine\n- **No Telemetry**: Zero data transmission to external servers\n\n---\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n**Ollama Connection Issues**\n```bash\n# Check Ollama status\nollama list\n\n# Restart Ollama service\nollama serve\n\n# Pull required models\nollama pull llama3\nollama pull nomic-embed-text\n```\n\n**ChromaDB Connection Problems**\n```bash\n# Verify ChromaDB is running\ncurl http://localhost:8000/api/v1/heartbeat\n\n# Restart ChromaDB with correct path\nchroma run --host 0.0.0.0 --port 8000 --path ./chronicle_data\n\n# Check ChromaDB logs\nchroma run --host 0.0.0.0 --port 8000 --path ./chronicle_data --log-level DEBUG\n```\n\n**Extension Issues**\n1. **VS Code Extension Not Working**\n   - Check extension activation in VS Code output panel\n   - Verify backend server is running on port 3001\n   - Ensure Ollama is accessible at localhost:11434\n\n2. **Browser Extension Not Tracking**\n   - Check extension permissions in browser settings\n   - Verify background script is active\n   - Check browser console for errors\n\n**Backend Service Issues**\n```bash\n# Check all services status\ncurl http://localhost:3001/api/health\ncurl http://localhost:11434/api/tags\ncurl http://localhost:8000/api/v1/heartbeat\n\n# Restart services in order\n# 1. ChromaDB\n# 2. Ollama\n# 3. Backend server\n# 4. Desktop app\n```\n\n---\n\n## Development \u0026 Contributing\n\n### Development Setup\n```bash\n# Frontend development\nnpm run dev\n\n# Backend development\ncd backend \u0026\u0026 npm run dev\n\n# Extension development\ncd vs-code-extension \u0026\u0026 npm run compile\n\n# Full stack development\nnpm run dev:all\n```\n\n### Project Structure\n```\nchronicle/\n├── backend/                    # Express.js backend\n│   ├── src/\n│   │   ├── services/          # Core services\n│   │   │   ├── agentService.ts\n│   │   │   ├── systemMonitor.ts\n│   │   │   └── vectorStore.ts\n│   │   └── server.ts          # Main server file\n│   └── package.json\n├── src/                       # React frontend\n│   ├── components/            # UI components\n│   ├── services/             # Frontend services\n│   └── App.tsx               # Main application\n├── chronicle-browser-extension/\n│   ├── background.js         # Service worker\n│   ├── content.js            # Content script\n│   └── manifest.json         # Extension manifest\n├── vs-code-extension/\n│   ├── src/\n│   │   ├── extension.ts      # Main extension file\n│   │   └── summarizer.ts     # AI summarization\n│   └── package.json\n└── electron/\n    └── main.ts               # Electron main process\n```\n\n---\n\n## Future Roadmap\n\n### Upcoming Features\n- **Mobile Companion App**: iOS/Android activity sync\n- **Team Analytics**: Collaborative productivity insights\n- **Advanced Visualizations**: Interactive activity charts and graphs\n- **Plugin System**: Extensible architecture for custom integrations\n- **Cloud Sync Option**: Optional encrypted cloud backup\n- **Multi-Language Support**: Support for additional programming languages\n\n### Performance Improvements\n- **Streaming Responses**: Real-time AI response streaming\n- **Incremental Indexing**: Efficient vector database updates\n- **Background Processing**: Non-blocking activity analysis\n- **Caching Layer**: Intelligent response caching system\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Acknowledgments\n\n- **LangChain**: For the powerful AI framework and tool ecosystem\n- **Ollama**: For enabling local AI model serving and inference\n- **ChromaDB**: For providing excellent vector database capabilities\n- **React Team**: For the excellent frontend framework and ecosystem\n- **Electron**: For enabling cross-platform desktop development\n- **VS Code Team**: For the comprehensive extension API\n- **Chrome Extensions**: For the robust browser extension platform\n\n**Chronicle** - Transform your digital activities into intelligent insights, completely locally and securely. Experience the future of productivity tracking with AI-powered analysis and narrative generation.\n\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofficiallyutso%2Fchronicle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fofficiallyutso%2Fchronicle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofficiallyutso%2Fchronicle/lists"}