{"id":51493999,"url":"https://github.com/kiritocode1/context-space","last_synced_at":"2026-07-07T13:01:53.503Z","repository":{"id":328073014,"uuid":"1106963664","full_name":"kiritocode1/context-space","owner":"kiritocode1","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-03T20:38:16.000Z","size":227,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-11T13:57:46.533Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/kiritocode1.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-30T10:09:49.000Z","updated_at":"2025-11-30T12:18:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kiritocode1/context-space","commit_stats":null,"previous_names":["kiritocode1/context-space"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kiritocode1/context-space","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiritocode1%2Fcontext-space","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiritocode1%2Fcontext-space/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiritocode1%2Fcontext-space/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiritocode1%2Fcontext-space/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiritocode1","download_url":"https://codeload.github.com/kiritocode1/context-space/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiritocode1%2Fcontext-space/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35228639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"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":[],"created_at":"2026-07-07T13:01:48.295Z","updated_at":"2026-07-07T13:01:53.411Z","avatar_url":"https://github.com/kiritocode1.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-Channel AI Memory System\n\nUnified multi-channel AI memory system with Redis short-term memory, Qdrant long-term memory, probabilistic identity linking, and multi-vector embeddings.\n\n## Architecture\n\n-   **Short-term Memory**: Upstash Redis KV + Upstash Vector Search (48hr TTL)\n-   **Long-term Memory**: Qdrant (persistent, cloud or local)\n-   **Identity Mapping**: MongoDB (Phase 2, cloud or local)\n-   **Embeddings**: OpenAI text-embedding-3-large (1536 dimensions)\n\n## Prerequisites\n\n-   Node.js 18+\n-   pnpm\n-   Upstash account (for Redis and Vector)\n-   OpenAI API key\n-   Optional: Docker \u0026 Docker Compose (for local Qdrant/MongoDB, or use cloud services)\n\n## Setup\n\n1. **Install dependencies:**\n\n```bash\npnpm install\n```\n\n2. **Set up Upstash services (required):**\n\n    - Create an [Upstash Redis](https://upstash.com/) account and database\n        - Go to [Upstash Console](https://console.upstash.com/)\n        - Create a new Redis database\n        - Copy the REST URL and token\n    - Create an [Upstash Vector](https://upstash.com/docs/vector/overall/getstarted) index\n        - In the Upstash Console, create a Vector index\n        - Set dimensions to 1536 (for text-embedding-3-large)\n        - Copy the REST URL and token\n\n3. **Set up optional services (choose one):**\n\n    **Option A: Use cloud services (recommended for production)**\n\n    - [Qdrant Cloud](https://cloud.qdrant.io/) - Create a cluster and get URL + API key\n    - [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) - Create a cluster and get connection string\n\n    **Option B: Use local Docker services (for development)**\n\n    ```bash\n    docker-compose up -d\n    ```\n\n    This starts:\n\n    - Qdrant (ports 6333, 6334)\n    - MongoDB (port 27017)\n\n4. **Configure environment:**\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your credentials:\n\n```\n# Upstash Redis (required)\nUPSTASH_REDIS_REST_URL=https://your-redis.upstash.io\nUPSTASH_REDIS_REST_TOKEN=your_redis_token\n\n# Upstash Vector (required)\nUPSTASH_VECTOR_REST_URL=https://your-vector.upstash.io\nUPSTASH_VECTOR_REST_TOKEN=your_vector_token\n\n# OpenAI (required)\nOPENAI_API_KEY=your_openai_key\n\n# Qdrant (optional - use cloud or local)\nQDRANT_URL=http://localhost:6333\nQDRANT_API_KEY=\n\n# MongoDB (optional - use Atlas or local)\nMONGODB_URI=mongodb://localhost:27017\nMONGODB_DB_NAME=context_space\n```\n\n5. **Initialize Qdrant collection:**\n   The collection will be auto-created on first API call when you start the dev server.\n\n6. **Start development server:**\n\n```bash\npnpm dev\n```\n\nThe server will start on `http://localhost:3000`\n\n## API Endpoints\n\n### POST `/api/memory/store`\n\nStore memory for a session.\n\n**Request:**\n\n```json\n{\n\t\"channel\": \"web\",\n\t\"channel_user_id\": \"a83d-session-cookie\",\n\t\"message\": {\n\t\t\"role\": \"user\",\n\t\t\"text\": \"Order AB123 delayed?\",\n\t\t\"summary\": \"user asking about order AB123 delay\"\n\t},\n\t\"metadata\": {\n\t\t\"ip\": \"192.168.1.1\",\n\t\t\"geo\": \"US\",\n\t\t\"lang\": \"en\"\n\t}\n}\n```\n\n**Response:**\n\n```json\n{\n\t\"success\": true,\n\t\"session_id\": \"session:web:hashed_id\",\n\t\"pseudo_user_id\": \"F29219AB-D41F\",\n\t\"stored_at\": 1735648392\n}\n```\n\n### POST `/api/memory/retrieve`\n\nRetrieve unified memory for a session.\n\n**Request:**\n\n```json\n{\n\t\"session_id\": \"session:web:hashed_id\",\n\t\"query_text\": \"Order status\"\n}\n```\n\n**Response:**\n\n```json\n{\n  \"memory_block\": \"Previous context: User asked about order AB123...\",\n  \"short_term\": {...},\n  \"long_term\": [...],\n  \"retrieved_at\": 1735648392\n}\n```\n\n### GET `/api/health`\n\nHealth check for all services.\n\n### GET `/api/identity/lookup?channel=web\u0026channel_user_id=user123`\n\nLookup pseudo_user_id by channel and channel_user_id.\n\n**Response:**\n\n```json\n{\n\t\"found\": true,\n\t\"pseudo_user_id\": \"F29219AB-D41F\",\n\t\"linked_sessions\": [\n\t\t{\n\t\t\t\"channel\": \"web\",\n\t\t\t\"channel_user_id\": \"hashed_id\",\n\t\t\t\"confidence\": 0.92\n\t\t},\n\t\t{\n\t\t\t\"channel\": \"whatsapp\",\n\t\t\t\"channel_user_id\": \"hashed_id\",\n\t\t\t\"confidence\": 0.85\n\t\t}\n\t]\n}\n```\n\n## Data Flow (7-Step Pipeline)\n\n**Incoming message → 7-step pipeline:**\n\n1. **Session Envelope Builder** - Normalize channel, user ID, metadata (hashes identifiers)\n2. **Embedding Generator** - Generate intent, emotion, product vectors (OpenAI text-embedding-3-large)\n3. **Short-term Redis Search** - Query existing Upstash Redis KV + Vector\n4. **Long-term Qdrant Search** - Query existing long-term memories\n5. **Probabilistic Identity Linking** - Match to existing pseudo_user_id or create new (Phase 2)\n6. **Store memory in Redis + Qdrant** - Write new memory to Upstash and Qdrant\n7. **Generate reply using relevant memory** - Inject memory into LLM context\n\n## Performance SLAs\n\n| Component               | SLA      |\n| ----------------------- | -------- |\n| Upstash Redis KV write  | \u003c 5 ms   |\n| Upstash Vector search   | \u003c 15 ms  |\n| Qdrant search           | \u003c 60 ms  |\n| Identity linking        | \u003c 10 ms  |\n| Total memory retrieval  | \u003c 120 ms |\n| Memory injection to LLM | \u003c 200 ms |\n\nAll operations include latency logging and SLA monitoring.\n\n## Security\n\n-   All identifiers are hashed (SHA-256) before storage\n-   No raw emails or phone numbers stored\n-   Pseudo-user-ID is non-reversible\n-   Encryption at rest + TLS in transit\n\n## Project Structure\n\n```\nlib/\n  types/              # TypeScript types and JSON schemas\n  db/                 # Database clients\n    redis.ts          # Upstash Redis + Vector clients\n    qdrant.ts         # Qdrant client\n    mongodb.ts        # MongoDB client (Phase 2)\n    init.ts           # Database initialization\n  services/           # Business logic services\n    embeddings.ts     # OpenAI embedding generation\n    session-envelope.ts # Session normalization + hashing\n    memory-storage.ts  # Redis + Qdrant write operations\n    memory-retrieval.ts # Unified memory retrieval\n    identity-linker.ts # Probabilistic identity linking (Phase 2)\n    identity-operations.ts # Identity helper functions\n  utils/              # Utilities\n    errors.ts         # Custom error classes\n    logger.ts         # Structured logging\n    hashing.ts        # SHA-256 identifier hashing\n  config/\n    env.ts            # Environment validation with Zod\napp/\n  api/\n    memory/\n      store/route.ts  # POST /api/memory/store\n      retrieve/route.ts # POST /api/memory/retrieve\n    identity/\n      lookup/route.ts # GET /api/identity/lookup\n    health/route.ts   # GET /api/health\n__tests__/            # Jest test files\ndocker-compose.yml    # Local Qdrant + MongoDB (optional)\n```\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Run tests\npnpm test\n\n# Run dev server\npnpm dev\n\n# Build for production\npnpm build\n\n# Start production server\npnpm start\n```\n\n## Docker Usage (Optional)\n\nDocker is only needed if you want to run Qdrant and MongoDB locally. For production, use cloud services:\n\n-   **Qdrant**: Use [Qdrant Cloud](https://cloud.qdrant.io/) (recommended)\n-   **MongoDB**: Use [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) (recommended)\n-   **Redis/Vector**: Always use Upstash (serverless, no Docker needed)\n\nIf using local Docker services:\n\n```bash\n# Start local Qdrant and MongoDB\ndocker-compose up -d\n\n# Stop services\ndocker-compose down\n\n# View logs\ndocker-compose logs -f\n```\n\n## Phase Status\n\n-   ✅ **Phase 1 (Core Memory)** - Implemented\n\n    -   Redis KV + Vector Search (Upstash)\n    -   Qdrant long-term memory\n    -   Multi-vector embeddings\n    -   Memory storage and retrieval\n\n-   ✅ **Phase 2 (Identity Linker)** - Implemented\n\n    -   Probabilistic identity matching algorithm\n    -   MongoDB identity map with confidence scores\n    -   Vector similarity (0.35 weight) - cosine similarity of intent vectors\n    -   Metadata similarity (0.25 weight) - IP, geo, lang matching\n    -   Behavior similarity (0.20 weight) - writing style analysis\n    -   Identifier overlap (0.20 weight) - order IDs, phone, email extraction\n    -   Match threshold: 0.82 (from PRD Section 8)\n    -   Cross-channel identity linking\n    -   Reverse lookup by channel + channel_user_id\n\n-   ✅ **Phase 2.5 (Intelligence Layer)** - Implemented\n\n    -   Urgency prediction (frustration + repetition + time sensitivity)\n    -   Problem extraction \u0026 criticality detection\n    -   Escalation to human supervisor\n    -   Action recommendation \u0026 execution framework\n\n-   ✅ **Phase 3 (Multi-channel SDK)** - Implemented\n\n    -   Base channel adapter with common functionality\n    -   Channel adapters: Web, WhatsApp, X/Twitter, Email, Phone\n    -   Factory function for easy adapter creation\n    -   SDK usage examples\n\n-   ✅ **Phase 4 (Admin Dashboard)** - Implemented\n    -   Admin API endpoints (critical problems, escalations, analytics)\n    -   Dashboard UI with real-time metrics\n    -   Escalation queue management\n    -   Problem filtering and status updates\n    -   Analytics and reporting\n\n## Gap Analysis\n\nSee [FINAL_GAP_ANALYSIS.md](./FINAL_GAP_ANALYSIS.md) for comprehensive comparison between current implementation and the original problem statement requirements.\n\n**Status: ✅ 100% Complete** - All requirements from the original problem statement have been implemented.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiritocode1%2Fcontext-space","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiritocode1%2Fcontext-space","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiritocode1%2Fcontext-space/lists"}