{"id":27620842,"url":"https://github.com/IhateCreatingUserNames2/Cognisphere","last_synced_at":"2025-04-23T07:01:47.364Z","repository":{"id":288078432,"uuid":"966759776","full_name":"IhateCreatingUserNames2/Cognisphere","owner":"IhateCreatingUserNames2","description":"Cognisphere ADK is an AI agent development framework built on Google's Agent Development Kit (ADK) ","archived":false,"fork":false,"pushed_at":"2025-04-22T20:44:17.000Z","size":536,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T21:26:35.190Z","etag":null,"topics":["a2a-protocol","google-adk","mcp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IhateCreatingUserNames2.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-04-15T12:15:09.000Z","updated_at":"2025-04-22T20:44:20.000Z","dependencies_parsed_at":"2025-04-22T21:23:35.476Z","dependency_job_id":null,"html_url":"https://github.com/IhateCreatingUserNames2/Cognisphere","commit_stats":null,"previous_names":["ihatecreatingusernames2/cognisphere"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IhateCreatingUserNames2%2FCognisphere","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IhateCreatingUserNames2%2FCognisphere/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IhateCreatingUserNames2%2FCognisphere/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IhateCreatingUserNames2%2FCognisphere/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IhateCreatingUserNames2","download_url":"https://codeload.github.com/IhateCreatingUserNames2/Cognisphere/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250386746,"owners_count":21422026,"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","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":["a2a-protocol","google-adk","mcp"],"created_at":"2025-04-23T07:01:23.891Z","updated_at":"2025-04-23T07:01:47.345Z","avatar_url":"https://github.com/IhateCreatingUserNames2.png","language":"Python","funding_links":[],"categories":["⚙️ Implementations \u0026 Libraries","🌟 Community Excellence","Server Implementations"],"sub_categories":["Domain-Specific Applications","🛠️ Developer Tools"],"readme":"![image](https://github.com/user-attachments/assets/c3feda1f-f341-46d7-ab45-5cd37600db22)\n# Cognisphere ADK: A Cognitive Architecture Framework\n\nCurrent Version: https://github.com/IhateCreatingUserNames2/Cognisphere/tree/main/cognisphere_adk_1.1 \n\nHow to Edit, Workflows, More technical Report: https://github.com/IhateCreatingUserNames2/Cognisphere/blob/main/cognisphere_how_to_edit.md \n\nCognisphere is an advanced cognitive architecture built with Google's Agent Development Kit (ADK). It features sophisticated memory, narrative, and identity capabilities, allowing for context-aware conversations with persistent state across sessions.\n\n## 🧠 Overview\n\nCognisphere implements a multi-agent architecture with specialized components:\n\n- **Orchestrator Agent**: Coordinates all sub-agents and handles user interaction\n- **Memory Agent**: Stores and retrieves memories of different types \n- **Narrative Agent**: Creates and manages narrative threads for experiences\n- **Identity Agent**: Manages different identities/personas the system can adopt\n- **MCP Agent**: Integrates with Model Context Protocol servers for extended capabilities\n- **AIRA Network**: Enables agent-to-agent communication\n\n## 🔄 Chat History and Session Management\n\nCognisphere maintains conversation history across sessions through a sophisticated system of session management, state persistence, and memory retrieval.\n\n### How Session Management Works\n\n1. **Session Service**: \n   - The application uses `DatabaseSessionService` for persistent storage of sessions\n   - Each session has a unique ID, and is associated with a user ID\n   - Sessions store both the conversation history (events) and state variables\n\n2. **State Management**:\n   - Session state is used to track context across conversations\n   - Different state prefixes have different scopes:\n     - No prefix: Session-specific state (current conversation only)\n     - `user:` prefix: User-specific state (shared across all sessions for that user)\n     - `app:` prefix: Application-wide state (shared across all users)\n     - `temp:` prefix: Temporary state (discarded after processing)\n\n3. **Memory Processing**:\n   - After each conversation, the `process_session_memory` function extracts key moments\n   - These are analyzed for emotional content and significance\n   - Important memories are stored in the database with embeddings for later retrieval\n\n4. **Session Continuity**:\n   - When a new conversation starts, the system can recall relevant memories from previous sessions\n   - This is done by the `_process_message_async` function which searches previous sessions for context\n   - Memories are retrieved based on relevance to the current query\n\n### User Interface for Sessions\n\nThe UI provides features for managing sessions:\n\n- View all conversation sessions\n- Switch between existing sessions\n- Create new conversations\n- Each session maintains its own state and history\n\n## 🧩 Core Components\n\n### Services\n\n- **Database Service** (`DatabaseService`): Persistent storage for memories and narratives\n- **Embedding Service** (`EmbeddingService`): Generates vector embeddings for semantic search\n- **Session Service** (`DatabaseSessionService`): Manages conversation sessions and state\n- **Identity Store** (`IdentityStore`): Handles identity creation and persistence\n![image](https://github.com/user-attachments/assets/8afc787e-cc62-4814-a1bd-f67bc9fcd7bb)\n\n### Data Models\n\n- **Memory**: Stores information with emotion and relevance scoring\n- **Narrative Thread**: Organizes experiences into coherent storylines\n- **Identity**: Represents different personas the system can embody\n\n### Integration Capabilities\n\n- **MCP Integration**: Connects with Model Context Protocol servers for extended tools\n\n   -  how to add MCP Servers, take for example the Claude.Json configuration : \nNPX\n{ \"mcpServers\": { \"memory\": { \"command\": \"npx\", \"args\": [ \"-y\", \"@modelcontextprotocol/server-memory\" ] } } }\nIn the UI, add mcpServers, NPC, and -y,@modelcontextprotoco/server-memory .... \n\nRefresh the Page to reload MCPServers. Sometimes it Fails. ***** It Only INSTALLS NPX SERVERS FOR NOW. \n-  You can add more commands thru .../mcpIntegration/server_installer.py , mcp_shared_environment.py .... \n-  read https://github.com/IhateCreatingUserNames2/Cognisphere/blob/main/mcp.md to know more\n \n\n\n\n- ![image](https://github.com/user-attachments/assets/cea2372c-043c-475d-893c-1be74bf207c0)![image](https://github.com/user-attachments/assets/9e7432ab-5b53-4d2d-9a9d-44ffa7fedd1a)\n\n\n- **AIRA Network**: Enables discovery and communication with other AI agents\n![image](https://github.com/user-attachments/assets/c36fded1-adc0-4a91-9ae5-345f74888356)\n\n## 🛠️ API Endpoints\n\n### Session Management\n- `/api/sessions/all`: Get all sessions for a user\n- `/api/sessions/create`: Create a new session\n- `/api/sessions`: Get recent sessions for a user\n- `/api/session/messages`: Get messages for a specific session\n\n### Chat\n- `/api/chat`: Process a user message through the orchestrator\n\n### Memory \u0026 Narrative\n- `/api/memories`: Get recalled memories for the current context\n- `/api/narratives`: Get active narrative threads\n\n### Identity\n- `/api/identities`: Get available identities\n- `/api/identities/switch`: Switch to a different identity\n\n### System\n- `/api/status`: Get system status information\n\n### Integrations\n- `/api/mcp/*`: MCP server management endpoints\n- `/api/aira/*`: AIRA network endpoints\n\n## 📂 Code Structure\n\nCognisphere follows a modular architecture:\n\n- `agents/`: Agent implementations (orchestrator, memory, narrative, identity)\n- `data_models/`: Data structures for memory, narrative, and identity\n- `services/`: Core services (database, embedding, etc.)\n- `web/`: Web routes for API endpoints\n- `tools/`: Tool implementations for agents\n- `callbacks/`: Callback functions for agent behavior\n- `mcpIntegration/`: Model Context Protocol integration\n- `a2a/`: Agent-to-agent communication\n\n## 🔧 Session Management Implementation Details\n\nThe session management system has these key components:\n\n1. **Session Initialization**:\n   ```python\n   def ensure_session(user_id: str, session_id: str) -\u003e Session:\n       \"\"\"\n       Ensure a session exists and is initialized with service objects.\n       \"\"\"\n       session = session_service.get_session(\n           app_name=app_name,\n           user_id=user_id,\n           session_id=session_id\n       )\n\n       if not session:\n           # Create a new session with initialized state\n           initial_state = {\n               \"user_preference_temperature_unit\": \"Celsius\"\n           }\n\n           session = session_service.create_session(\n               app_name=app_name,\n               user_id=user_id,\n               session_id=session_id,\n               state=initial_state\n           )\n\n           # Ensure identity catalog is loaded into session state\n           initialize_identity_state(session)\n\n       return session\n   ```\n\n2. **Message Processing with Context**:\n   ```python\n   async def _process_message_async(user_id: str, session_id: str, message: str):\n       # Retrieve previous session's context\n       previous_sessions = session_service.list_sessions(\n           app_name=app_name,\n           user_id=user_id\n       )\n\n       # Get memories from previous sessions to inject context\n       for prev_session in sorted_sessions[:3]:  # Limit to last 3 sessions\n           try:\n               memories_result = recall_memories(\n                   tool_context=ToolContext(\n                       state={},\n                       agent_name=\"memory_agent\"\n                   ),\n                   query=message,\n                   limit=3,\n                   identity_filter=None,\n                   include_all_identities=False\n               )\n\n               # Check if memories_result is a valid dictionary with memories\n               if isinstance(memories_result, dict) and \"memories\" in memories_result:\n                   context_memories.extend(memories_result.get(\"memories\", []))\n           except Exception as memory_error:\n               print(f\"Error recalling memories for session {prev_session.id}: {memory_error}\")\n               continue\n   ```\n\n3. **Frontend Session Management**:\n   ```javascript\n   // Switch to a different session\n   async function switchToSession(sessionId) {\n       console.log(`Switching to session: ${sessionId}`);\n\n       if (sessionId === currentSessionId) {\n           console.log('Already on this session');\n           return;\n       }\n\n       try {\n           // Update the current session ID\n           currentSessionId = sessionId;\n\n           // Save to localStorage\n           localStorage.setItem('currentSessionId', currentSessionId);\n\n           // Load messages for this session\n           await loadSessionMessages(sessionId);\n\n           // Update UI to show which session is active\n           document.querySelectorAll('.session-item').forEach(item =\u003e {\n               if (item.dataset.id === sessionId) {\n                   item.classList.add('active');\n               } else {\n                   item.classList.remove('active');\n               }\n           });\n\n           // Also refresh related data for this session\n           updateMemories();\n           updateNarrativeThreads();\n\n           console.log(`Successfully switched to session: ${sessionId}`);\n       } catch (error) {\n           console.error('Error switching sessions:', error);\n           addMessageToChat('assistant', `Error loading session: ${error.message}`);\n       }\n   }\n   ```\n\n## 🔄 Memory Processing\n\nAfter each conversation, Cognisphere extracts important memories:\n\n```python\ndef process_session_memory(session, identity_id):\n    \"\"\"\n    Transform session into meaningful memories by analyzing emotional content,\n    extracting significant moments, and connecting them to identities.\n    \"\"\"\n    # Extract user messages\n    user_messages = []\n    for event in session.events:\n        if event.author == \"user\" and event.content and event.content.parts:\n            text = event.content.parts[0].text\n            if text:\n                user_messages.append(text)\n\n    # Analyze emotional content\n    combined_text = \" \".join(user_messages)\n    emotion_data = analyze_emotion(combined_text)\n\n    # Extract key moments (most emotionally significant or newest)\n    key_moments = []\n    \n    # Always include the most recent message\n    if user_messages:\n        key_moments.append({\"content\": user_messages[-1], \"importance\": 1.0})\n\n    # Include high-emotion messages\n    if len(user_messages) \u003e 1:\n        for msg in user_messages[:-1]:\n            msg_emotion = analyze_emotion(msg)\n            if msg_emotion[\"score\"] \u003e 0.7:\n                key_moments.append({\"content\": msg, \"importance\": msg_emotion[\"score\"]})\n\n    # Create memories for each key moment\n    for moment in key_moments:\n        # Determine memory type based on content and emotion\n        if emotion_data[\"emotion_type\"] in [\"joy\", \"excitement\", \"curiosity\"]:\n            memory_type = \"emotional\"\n        elif emotion_data[\"score\"] \u003e 0.8:\n            memory_type = \"flashbulb\"  # Highly significant memories\n        else:\n            memory_type = \"explicit\"  # Regular factual memories\n\n        # Store memory in database with embedding\n        memory = Memory(\n            content=moment[\"content\"],\n            memory_type=memory_type,\n            emotion_data=emotion_data,\n            source=\"session\",\n            identity_id=identity_id,\n            source_identity=identity_id\n        )\n        \n        embedding = embedding_service.encode(moment[\"content\"])\n        if embedding:\n            db_service.add_memory(memory, embedding)\n```\n\n## 🚀 Getting Started\n\n1. Install dependencies:\n   ```bash\n   pip install google-adk litellm google-genai sentence-transformers flask openai\n   ```\n\n2. Run the application:\n   ```bash\n   python app.py\n   ```\n\n3. Access the UI at `http://localhost:8095`\n\n## 🔧 Troubleshooting Session Management\n\nIf chat history is not persisting between sessions:\n\n1. Check that `DatabaseSessionService` is correctly initialized\n2. Verify that session IDs are being properly passed between requests\n3. Ensure the localStorage mechanism in the frontend is working correctly\n4. Check backend logs for any errors during session retrieval or storage\n5. Verify that the `/api/sessions/all` endpoint is correctly identifying user sessions\n6. Make sure session switching in the UI is properly updating session history\n\n## 📝 Future Improvements\n\n- Enhance memory processing for better context retrieval ( The Memory Agent needs to be Linked Correctly with the Narrative Agent ) \n- Implement more sophisticated narrative creation \n- Enhance frontend session management with search capabilities\n- Add metadata display for memories and narrative connections\n- Better UI\n- Attachments\n- Artifacts\n  \n## Added Stuff \n - 04.22 - OpenRouter API Key On the UI \n![image](https://github.com/user-attachments/assets/55bd1543-876c-4e19-8bcf-da577b172bc3)\n\n\n## 📝 Know Issues:\n- Async issues\n- Deprecated libs\n- MCP sometimes fails\n- AiraHub Needs to be Updated for auth or use the old AiraHub code. \n- Invalid Date in Sessions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIhateCreatingUserNames2%2FCognisphere","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIhateCreatingUserNames2%2FCognisphere","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIhateCreatingUserNames2%2FCognisphere/lists"}