{"id":51145173,"url":"https://github.com/magnexis/memory-os","last_synced_at":"2026-06-26T02:03:47.968Z","repository":{"id":356842398,"uuid":"1234287585","full_name":"magnexis/memory-os","owner":"magnexis","description":"MemoryOS is a cinematic spatial memory operating system.  It is built to organize memories, projects, screenshots, ideas, relationships, locations, music, dreams, and archived moments as a living interactive graph.","archived":false,"fork":false,"pushed_at":"2026-06-25T22:42:08.000Z","size":3373,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T23:11:47.983Z","etag":null,"topics":["api","cli","css","javascript","operating-system","release","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magnexis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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":"2026-05-10T01:41:22.000Z","updated_at":"2026-06-25T22:42:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/magnexis/memory-os","commit_stats":null,"previous_names":["theworker02/memory-os","magnexis/memory-os"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/magnexis/memory-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnexis%2Fmemory-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnexis%2Fmemory-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnexis%2Fmemory-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnexis%2Fmemory-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magnexis","download_url":"https://codeload.github.com/magnexis/memory-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magnexis%2Fmemory-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34799572,"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-06-26T02:00:06.560Z","response_time":106,"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":["api","cli","css","javascript","operating-system","release","typescript"],"created_at":"2026-06-26T02:03:42.371Z","updated_at":"2026-06-26T02:03:47.952Z","avatar_url":"https://github.com/magnexis.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MemoryOS\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-19-61dafb?logo=react\u0026logoColor=0b1020)](https://react.dev/)\n[![Vite](https://img.shields.io/badge/Vite-7-646cff?logo=vite\u0026logoColor=white)](https://vite.dev/)\n[![Fastify](https://img.shields.io/badge/Fastify-5-111827?logo=fastify\u0026logoColor=white)](https://fastify.dev/)\n[![Prisma](https://img.shields.io/badge/Prisma-6.19-2d3748?logo=prisma\u0026logoColor=white)](https://www.prisma.io/)\n[![MemoryOS API](https://img.shields.io/badge/MemoryOS%20API-v0.1.0-62f0ff)](docs/API.md)\n[![Docker](https://img.shields.io/badge/Docker-ready-2496ed?logo=docker\u0026logoColor=white)](docker-compose.yml)\n[![Vercel](https://img.shields.io/badge/Vercel-ready-000000?logo=vercel\u0026logoColor=white)](docs/DEPLOYMENT.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-facc15.svg)](LICENSE)\n\nMemoryOS is a cinematic spatial memory operating system.\n\nIt is built to organize memories, projects, screenshots, ideas, relationships, locations, music, dreams, and archived moments as a living interactive graph.\n\nIt is not a standard notes app.\n\nIt is not a normal task manager.\n\nIt is not a simple AI chat shell.\n\nMemoryOS is designed as a futuristic archive environment: a place where personal data becomes spatial, searchable, replayable, and emotionally navigable.\n\nThe application combines a premium dark interface, animated graph systems, timeline playback, ambient visual layers, real routes, working settings, developer API tooling, and a modular backend.\n\nThe root command starts both sides:\n\n```bash\nnpm run dev\n```\n\nThat command runs the frontend and backend together.\n\n---\n\n## Table Of Contents\n\n- [What MemoryOS Is](#what-memoryos-is)\n- [Real UI Screenshots](#real-ui-screenshots)\n- [Core Features](#core-features)\n- [Application Routes](#application-routes)\n- [Architecture](#architecture)\n- [Repository Structure](#repository-structure)\n- [Frontend Stack](#frontend-stack)\n- [Backend Stack](#backend-stack)\n- [Quick Start](#quick-start)\n- [Environment Variables](#environment-variables)\n- [Running The App](#running-the-app)\n- [Available Scripts](#available-scripts)\n- [Authentication And Onboarding](#authentication-and-onboarding)\n- [Memory Stream](#memory-stream)\n- [Node Atlas](#node-atlas)\n- [Memory Space](#memory-space)\n- [Timeline](#timeline)\n- [Archive](#archive)\n- [Music System](#music-system)\n- [Developer Console](#developer-console)\n- [MemoryOS API](#memoryos-api)\n- [API Key Usage](#api-key-usage)\n- [Release Artifacts](#release-artifacts)\n- [Deployment](#deployment)\n- [Docker](#docker)\n- [Security Model](#security-model)\n- [Offline And Sync Behavior](#offline-and-sync-behavior)\n- [Performance Notes](#performance-notes)\n- [Testing And Verification](#testing-and-verification)\n- [Troubleshooting](#troubleshooting)\n- [Documentation Map](#documentation-map)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What MemoryOS Is\n\nMemoryOS is a desktop-grade web application for spatial memory management.\n\nThe interface treats memories as nodes.\n\nProjects become hubs.\n\nRelationships become connection maps.\n\nLocations become anchors.\n\nTimeline periods become cinematic rails.\n\nMusic becomes an emotional layer.\n\nDeveloper tools expose the archive through a scoped API.\n\nThe product goal is simple:\n\n\u003e Make personal history feel explorable.\n\nMemoryOS aims to feel like:\n\n- a digital brain\n- a neural archive\n- a cinematic operating system\n- a tactical investigation board\n- a living personal database\n- a spatial creative workspace\n- a memory replay engine\n- a developer-accessible archive platform\n\nThe first version is intentionally practical.\n\nIt avoids fake impossible AI.\n\nIt uses achievable systems:\n\n- metadata analysis\n- fuzzy search\n- graph relationships\n- local persistence\n- WebSocket events\n- upload handling\n- API keys\n- route-based UI state\n- animated charts\n- interactive nodes\n- scoped developer endpoints\n\nThe uniqueness comes from presentation, interaction, and structure.\n\n---\n\n## Real UI Screenshots\n\nThese screenshots are captured from the running MemoryOS application with `agent-browser`.\n\nThey are not mockups.\n\nThey are not generated illustrations.\n\nThey reflect the current local UI.\n\n### Node Atlas\n\n![MemoryOS Node Atlas](assets/screenshots/node-atlas-real.png)\n\nThe Node Atlas is the cleaner graph workspace.\n\nIt is built for arranging memory nodes without overcrowding the viewport.\n\nIt includes:\n\n- React Flow graph rendering\n- draggable memory nodes\n- connection lines\n- compact command controls\n- responsive inspector rail\n- 3D constellation mode\n- clean graph-first layout\n\n### Cinematic Timeline\n\n![MemoryOS Timeline](assets/screenshots/timeline-real.png)\n\nThe timeline route turns memory history into a cinematic rail.\n\nIt includes:\n\n- period controls\n- playback controls\n- event clusters\n- density visualization\n- ECharts analytics\n- animated route transitions\n- activity heat data\n\n### Developer Console\n\n![MemoryOS Developer Console](assets/screenshots/developer-console-real.png)\n\nThe developer console exposes MemoryOS as an integration platform.\n\nIt includes:\n\n- API key generation\n- scope selection\n- webhook settings\n- environment helpers\n- live API inspector\n- integration logs\n- release-ready developer workflows\n\n---\n\n## Core Features\n\nMemoryOS includes a full frontend and backend.\n\nThe current build contains:\n\n- cinematic dark-only interface\n- authenticated entry flow\n- first-run onboarding\n- configurable notification timer\n- real route rendering\n- protected application shell\n- global search\n- quick capture\n- memory node graph\n- dedicated Node Atlas route\n- 3D constellation mode\n- timeline replay interface\n- archive filtering\n- dreamspace panels\n- relationship views\n- location archive panels\n- music linking\n- generated Web Audio loops\n- Spotify URL parsing\n- media upload UI\n- settings persistence\n- profile modules\n- sync diagnostics\n- system dashboard\n- developer console\n- API key generation\n- webhook simulation\n- public MemoryOS API endpoints\n- Fastify backend\n- Prisma schema\n- PostgreSQL support\n- Redis support with graceful local fallback\n- JWT authentication backend routes\n- WebSocket pulse channel\n- Docker setup\n- GitHub templates\n- CI workflow\n- release artifacts\n\nThe app is meant to be usable locally immediately.\n\nIt also has a clear path to production deployment.\n\n---\n\n## Application Routes\n\nMemoryOS supports auth routes, core routes, and extended workspace routes.\n\n### Auth Routes\n\n- `/auth/login`\n- `/auth/register`\n- `/auth/forgot-password`\n- `/auth/reset-password`\n- `/auth/onboarding`\n- `/auth/logout`\n\n### Primary Routes\n\n- `/memory-stream`\n- `/archive`\n- `/timeline`\n- `/nodes`\n- `/developer-console`\n- `/system`\n- `/insights`\n- `/sync`\n- `/profile`\n- `/settings`\n\n### Extended Routes\n\n- `/dashboard`\n- `/memory-space`\n- `/projects`\n- `/dreamspace`\n- `/relationships`\n- `/locations`\n- `/music`\n- `/ideas`\n- `/media`\n\nThe application shell is protected.\n\nUsers without a local session are redirected to `/auth/login`.\n\nThe demo auth flow persists a local session in browser storage.\n\n---\n\n## Architecture\n\nMemoryOS is split into two primary workspaces.\n\nThe frontend is a Vite React application.\n\nThe backend is a Fastify TypeScript API.\n\nThe project uses npm workspaces.\n\nThe root package orchestrates both sides.\n\n```text\nmemoryos/\n├── frontend/\n├── backend/\n├── docs/\n├── assets/\n├── scripts/\n├── release-artifacts/\n├── .github/\n├── README.md\n├── CONTRIBUTING.md\n├── CHANGELOG.md\n├── SECURITY.md\n├── LICENSE\n├── .gitignore\n├── docker-compose.yml\n├── package.json\n└── package-lock.json\n```\n\nThe frontend and backend can be developed independently.\n\nThey can also run together through the root command.\n\nThe frontend talks to the backend through `/api`.\n\nThe backend exposes REST endpoints and a WebSocket channel.\n\nThe database layer is Prisma.\n\nThe default database target is PostgreSQL.\n\nRedis is supported for caching.\n\nRedis is optional during local development.\n\nIf Redis is unavailable, the backend continues without cache.\n\n---\n\n## Repository Structure\n\n### Root\n\n```text\n.\n├── package.json\n├── docker-compose.yml\n├── README.md\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── SECURITY.md\n├── LICENSE\n└── .gitignore\n```\n\nThe root package contains shared scripts.\n\nThe most important root script is:\n\n```bash\nnpm run dev\n```\n\nThat starts both the frontend and backend.\n\n### Frontend\n\n```text\nfrontend/\n├── public/\n├── src/\n├── index.html\n├── package.json\n├── tailwind.config.ts\n├── vite.config.ts\n└── tsconfig.json\n```\n\nThe frontend source includes:\n\n- `components/`\n- `pages/`\n- `store/`\n- `hooks/`\n- `lib/`\n- `data/`\n- `styles/`\n\n### Backend\n\n```text\nbackend/\n├── prisma/\n├── src/\n├── uploads/\n├── Dockerfile\n├── package.json\n└── tsconfig.json\n```\n\nThe backend source includes:\n\n- `modules/`\n- `plugins/`\n- `utils/`\n- `config.ts`\n- `server.ts`\n\n### Documentation\n\n```text\ndocs/\n├── API.md\n├── ARCHITECTURE.md\n├── DEPLOYMENT.md\n├── GITHUB.md\n└── RELEASE.md\n```\n\n### Assets\n\n```text\nassets/\n└── screenshots/\n```\n\nThe screenshot directory contains real README screenshots.\n\n### Release Artifacts\n\n```text\nrelease-artifacts/\n├── memoryos-site-v0.1.0.zip\n├── memoryos-site-v0.1.0.zip.sha256\n├── memoryos-api-v0.1.0.zip\n└── memoryos-api-v0.1.0.zip.sha256\n```\n\nThese zip files are downloadable GitHub release assets.\n\n---\n\n## Frontend Stack\n\nThe frontend uses:\n\n- Vite\n- React\n- TypeScript\n- Tailwind CSS\n- Framer Motion\n- GSAP\n- Three.js\n- React Three Fiber\n- Zustand\n- React Router\n- Radix UI\n- React Flow\n- TanStack Query\n- Apache ECharts\n- Fuse.js\n- Lucide React\n\nThe frontend is intentionally dark mode only.\n\nThe UI language uses:\n\n- matte black backgrounds\n- cyan signal accents\n- subtle amber highlights\n- tactical grid layers\n- animated ambient particles\n- route-aware lighting\n- responsive panels\n- soft glow states\n- compact operating-system controls\n\nThe design avoids:\n\n- white backgrounds\n- generic dashboard styling\n- bootstrap appearance\n- dead controls\n- placeholder routes\n- static-only data sections\n\n---\n\n## Backend Stack\n\nThe backend uses:\n\n- Node.js\n- TypeScript\n- Fastify\n- Prisma\n- PostgreSQL\n- Redis\n- JWT\n- bcrypt\n- Zod\n- Fastify rate limiting\n- Fastify multipart uploads\n- Fastify WebSocket\n- Pino structured logging\n- Docker\n\nBackend responsibilities include:\n\n- authentication routes\n- developer API key routes\n- MemoryOS public API routes\n- memory record endpoints\n- project endpoints\n- media upload endpoints\n- search endpoints\n- smart link endpoints\n- health endpoint\n- WebSocket pulse channel\n- Prisma database access\n- Redis plugin\n\n---\n\n## Quick Start\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nCreate environment config:\n\n```bash\ncp backend/.env.example backend/.env\n```\n\nStart local infrastructure:\n\n```bash\ndocker compose up -d postgres redis\n```\n\nGenerate Prisma client:\n\n```bash\nnpm run db:generate\n```\n\nRun migrations:\n\n```bash\nnpm run db:migrate\n```\n\nStart the app:\n\n```bash\nnpm run dev\n```\n\nOpen the frontend:\n\n```text\nhttp://localhost:5173\n```\n\nIf port `5173` is already in use, Vite will choose the next available port.\n\nThe backend defaults to:\n\n```text\nhttp://localhost:4400\n```\n\nThe health endpoint is:\n\n```text\nhttp://localhost:4400/api/health\n```\n\n---\n\n## Environment Variables\n\nBackend variables live in:\n\n```text\nbackend/.env\n```\n\nUse:\n\n```text\nbackend/.env.example\n```\n\nas the starting point.\n\nImportant variables:\n\n```bash\nDATABASE_URL=\"postgresql://memoryos:memoryos@localhost:5432/memoryos\"\nREDIS_URL=\"redis://localhost:6379\"\nJWT_SECRET=\"replace-with-a-secure-secret\"\nCOOKIE_SECRET=\"replace-with-a-secure-cookie-secret\"\nFRONTEND_ORIGIN=\"http://localhost:5173\"\nPORT=4400\n```\n\nFor production:\n\n- use strong secrets\n- use managed PostgreSQL\n- use managed Redis\n- set `FRONTEND_ORIGIN` to the deployed site domain\n- run Prisma migrations during deployment\n\n---\n\n## Running The App\n\nRun both frontend and backend:\n\n```bash\nnpm run dev\n```\n\nRun frontend only:\n\n```bash\nnpm run dev:frontend\n```\n\nRun backend only:\n\n```bash\nnpm run dev:backend\n```\n\nBuild everything:\n\n```bash\nnpm run build\n```\n\nLint everything:\n\n```bash\nnpm run lint\n```\n\nTypecheck everything:\n\n```bash\nnpm run typecheck\n```\n\n---\n\n## Available Scripts\n\n### Root Scripts\n\n```bash\nnpm run dev\n```\n\nRuns frontend and backend together.\n\n```bash\nnpm run build\n```\n\nBuilds frontend and backend.\n\n```bash\nnpm run lint\n```\n\nRuns ESLint for both workspaces.\n\n```bash\nnpm run typecheck\n```\n\nRuns TypeScript checks for both workspaces.\n\n```bash\nnpm run db:generate\n```\n\nGenerates Prisma client.\n\n```bash\nnpm run db:migrate\n```\n\nRuns local Prisma migrations.\n\n### Frontend Scripts\n\n```bash\nnpm --workspace frontend run dev\nnpm --workspace frontend run build\nnpm --workspace frontend run preview\nnpm --workspace frontend run lint\nnpm --workspace frontend run typecheck\n```\n\n### Backend Scripts\n\n```bash\nnpm --workspace backend run dev\nnpm --workspace backend run build\nnpm --workspace backend run start\nnpm --workspace backend run lint\nnpm --workspace backend run typecheck\nnpm --workspace backend run db:generate\nnpm --workspace backend run db:migrate\n```\n\n---\n\n## Authentication And Onboarding\n\nMemoryOS includes a working local auth flow.\n\nThe auth routes are:\n\n- `/auth/login`\n- `/auth/register`\n- `/auth/forgot-password`\n- `/auth/reset-password`\n- `/auth/onboarding`\n- `/auth/logout`\n\nThe current frontend auth flow stores a local session object.\n\nThat session gates the application shell.\n\nIf no session exists, app routes redirect to `/auth/login`.\n\nAfter the first successful sign-in or registration, the user goes through onboarding.\n\nOnboarding configures:\n\n- operating density\n- basic archive orientation\n- notification behavior\n\nOnboarding completion is persisted locally.\n\nLogout removes the local session.\n\nBackend JWT auth routes also exist.\n\nProduction auth should connect the frontend session to backend JWT cookies.\n\n---\n\n## Memory Stream\n\nRoute:\n\n```text\n/memory-stream\n```\n\nThe Memory Stream is the operational landing page.\n\nIt gives a live sense of archive activity.\n\nIt includes:\n\n- memory filtering\n- stream-style records\n- active modules\n- status cards\n- system actions\n- local state interactions\n\nThis route is intended to feel like the main operating surface.\n\n---\n\n## Node Atlas\n\nRoute:\n\n```text\n/nodes\n```\n\nThe Node Atlas is a graph-first workspace.\n\nIt is separate from the denser Memory Space route.\n\nIt was rebuilt to avoid overcrowding.\n\nIt includes:\n\n- React Flow graph canvas\n- draggable memory nodes\n- animated relationship links\n- selected-memory inspector\n- compact action bar\n- responsive bottom drawer on smaller screens\n- desktop right-side inspector rail\n- 3D constellation toggle\n- orbit depth controls\n\nPrimary controls:\n\n- Inspect\n- Focus\n- Connect\n- Add Node\n- 3D Map\n\nThe graph remains usable across viewport sizes.\n\nThe inspector no longer crushes the graph on smaller screens.\n\n---\n\n## Memory Space\n\nRoute:\n\n```text\n/memory-space\n```\n\nMemory Space is the full cinematic spatial archive.\n\nIt intentionally has more atmosphere and more interface layers than Node Atlas.\n\nIt includes:\n\n- infinite canvas\n- memory nodes\n- animated links\n- temporal scrubber\n- smart linking panel\n- focus mode\n- connect mode\n- replay mode\n- inspect mode\n- group mode\n- 3D constellation mode\n\nMemory nodes can represent:\n\n- photos\n- screenshots\n- notes\n- videos\n- audio\n- links\n- location data\n- tags\n- emotions\n- weather\n- project references\n\n---\n\n## Timeline\n\nRoute:\n\n```text\n/timeline\n```\n\nThe timeline route presents memories as a cinematic rail.\n\nIt includes:\n\n- horizontal memory traversal\n- period controls\n- playback controls\n- memory density visuals\n- cluster previews\n- ECharts analytics\n- animated panels\n- route transitions\n\nTimeline zoom modes include:\n\n- year\n- month\n- week\n- day\n\nThe goal is to make memory review feel closer to editing film than browsing a calendar.\n\n---\n\n## Archive\n\nRoute:\n\n```text\n/archive\n```\n\nThe archive route provides searchable memory storage.\n\nIt includes:\n\n- text filtering\n- record cards\n- smart actions\n- local persistence\n- duplicate-style recovery concepts\n- advanced search surfaces\n\nIt is designed to feel more like a recovery terminal than a file list.\n\n---\n\n## Music System\n\nRoute:\n\n```text\n/music\n```\n\nThe music route contains music-specific linking.\n\nThe music linker is intentionally scoped to this route only.\n\nIt supports:\n\n- generated Web Audio memory loops\n- playable audio textures\n- Spotify URL parsing\n- Spotify embed URLs\n- song-memory linking\n- soundtrack-like memory records\n- waveform-style visual panels\n\nSupported Spotify URLs include:\n\n- tracks\n- albums\n- playlists\n- artists\n\nThe system does not fake music generation through external AI.\n\nGenerated loops use practical browser audio APIs.\n\n---\n\n## Developer Console\n\nRoute:\n\n```text\n/developer-console\n```\n\nThe Developer Console turns MemoryOS into an integration platform.\n\nIt includes:\n\n- API key creation\n- API key scopes\n- environment profile controls\n- webhook endpoint configuration\n- webhook event toggles\n- webhook secret generation\n- `.env` helper output\n- API inspector\n- endpoint examples\n- live response viewer\n- local fallback key generation\n- backend-registered key support\n\nThe top shell also includes a compact Developers control.\n\nThat control opens developer tooling from anywhere in the app.\n\n---\n\n## MemoryOS API\n\nBase API URL:\n\n```text\nhttp://localhost:4400/api\n```\n\nHealth check:\n\n```text\nGET /api/health\n```\n\nDeveloper key management:\n\n```text\nGET    /api/developer/keys\nPOST   /api/developer/keys\nPATCH  /api/developer/keys/:id\nDELETE /api/developer/keys/:id\n```\n\nPublic integration API:\n\n```text\nGET /api/v1/status\nGET /api/v1/memories\nGET /api/v1/graph\nGET /api/v1/search\n```\n\nThe `/api/v1/*` routes require a MemoryOS API key.\n\nAPI keys are passed as bearer tokens.\n\n---\n\n## API Key Usage\n\nGenerate an API key in:\n\n```text\n/developer-console\n```\n\nStore it in your environment:\n\n```bash\nMEMORYOS_API_KEY=mos_test_or_live_value\n```\n\nCall the status endpoint:\n\n```bash\ncurl http://localhost:4400/api/v1/status \\\n  -H \"Authorization: Bearer $MEMORYOS_API_KEY\"\n```\n\nCall memories:\n\n```bash\ncurl \"http://localhost:4400/api/v1/memories?take=25\" \\\n  -H \"Authorization: Bearer $MEMORYOS_API_KEY\"\n```\n\nCall graph:\n\n```bash\ncurl http://localhost:4400/api/v1/graph \\\n  -H \"Authorization: Bearer $MEMORYOS_API_KEY\"\n```\n\nCall search:\n\n```bash\ncurl \"http://localhost:4400/api/v1/search?q=rain\" \\\n  -H \"Authorization: Bearer $MEMORYOS_API_KEY\"\n```\n\nScopes include:\n\n- `memories:read`\n- `memories:write`\n- `search:read`\n- `graph:read`\n- `webhooks:write`\n\nSee [API.md](docs/API.md) for more details.\n\n---\n\n## Release Artifacts\n\nActual downloadable release artifacts are stored in:\n\n```text\nrelease-artifacts/\n```\n\nCurrent release assets:\n\n```text\nrelease-artifacts/memoryos-site-v0.1.0.zip\nrelease-artifacts/memoryos-site-v0.1.0.zip.sha256\nrelease-artifacts/memoryos-api-v0.1.0.zip\nrelease-artifacts/memoryos-api-v0.1.0.zip.sha256\n```\n\n### Site Artifact\n\nThe site artifact contains the production build from:\n\n```text\nfrontend/dist\n```\n\nUse it for:\n\n- GitHub Release uploads\n- static hosting\n- manual deployment\n- preview distribution\n\n### API Artifact\n\nThe API artifact contains:\n\n- compiled backend `dist`\n- Prisma schema and migrations\n- backend `package.json`\n- backend `Dockerfile`\n- backend `.env.example`\n- root `package-lock.json`\n- docs\n- license\n- changelog\n\nUse it for:\n\n- GitHub Release uploads\n- backend deployment handoff\n- API server distribution\n- Docker-based deployment preparation\n\n### Rebuilding Release Assets\n\nRun:\n\n```bash\nnpm run build\n```\n\nThen package the site and API from the build output.\n\nThe current release assets were generated from the production build.\n\n---\n\n## Deployment\n\n### Frontend Deployment\n\nThe frontend is Vercel-ready.\n\nRecommended settings:\n\n```text\nRoot Directory: frontend\nBuild Command: npm run build\nOutput Directory: dist\n```\n\nSet API URL variables as needed.\n\nIf the backend is deployed separately, configure the frontend to point to it.\n\n### Backend Deployment\n\nThe backend is Docker-ready.\n\nRecommended targets:\n\n- Railway\n- Render\n- Fly.io\n- Docker host\n- Kubernetes\n\nRequired services:\n\n- PostgreSQL\n- Redis\n\nRedis may be optional for simple local use.\n\nIt is recommended for production cache behavior.\n\n### Migration Command\n\nRun before starting production:\n\n```bash\nnpx prisma migrate deploy\n```\n\n---\n\n## Docker\n\nStart local infrastructure:\n\n```bash\ndocker compose up -d postgres redis\n```\n\nStop local infrastructure:\n\n```bash\ndocker compose down\n```\n\nReset volumes:\n\n```bash\ndocker compose down -v\n```\n\nThe backend Dockerfile lives at:\n\n```text\nbackend/Dockerfile\n```\n\n---\n\n## Security Model\n\nMemoryOS includes baseline security features.\n\nImplemented backend security includes:\n\n- JWT setup\n- cookie support\n- CSRF protection plugin\n- helmet headers\n- CORS configuration\n- rate limiting\n- input validation with Zod\n- bcrypt password hashing support\n- Prisma query safety\n- sanitized upload filenames\n- file size and type constraints\n- scoped API keys\n- key prefix lookup\n- key revocation\n\nProduction recommendations:\n\n- rotate secrets\n- use HTTPS only\n- use secure cookies\n- restrict CORS origins\n- use managed database credentials\n- back up PostgreSQL\n- store uploaded media in object storage\n- scan uploaded media where appropriate\n- avoid committing `.env` files\n\nSee [SECURITY.md](SECURITY.md).\n\n---\n\n## Offline And Sync Behavior\n\nMemoryOS includes local-first behavior in the UI.\n\nFeatures include:\n\n- local record persistence\n- offline queue storage\n- sync status controls\n- local backup snapshots\n- exportable archive JSON\n- service worker registration in production\n- WebSocket status behavior\n\nOffline captures can be queued.\n\nThe sync route can flush local queue state.\n\nThe settings route exposes storage and backup controls.\n\n---\n\n## Performance Notes\n\nMemoryOS uses several visual systems.\n\nPerformance matters.\n\nCurrent optimization strategies include:\n\n- Vite chunking\n- lazy-loaded routes\n- React Flow for graph rendering\n- ECharts loaded as a chart chunk\n- Three.js separated as its own chunk\n- GSAP separated as an animation chunk\n- local state scoped through Zustand\n- responsive panel layouts\n- route-level code splitting\n- CSS-driven ambient effects\n- controlled notification timers\n\nLarge chunks are expected for:\n\n- Three.js\n- React Flow\n- ECharts\n\nThese are split from the main app bundle.\n\n---\n\n## Testing And Verification\n\nRun the full local verification set:\n\n```bash\nnpm run typecheck\nnpm run lint\nnpm run build\n```\n\nCurrent verification status:\n\n- TypeScript passes\n- ESLint passes\n- Production build passes\n- Auth routes return 200 locally\n- Favicon route returns 200 locally\n- API health returns 200 locally\n\nManual routes to check:\n\n- `/auth/login`\n- `/auth/onboarding`\n- `/memory-stream`\n- `/nodes`\n- `/timeline`\n- `/developer-console`\n- `/settings`\n- `/music`\n\nUseful browser smoke checks:\n\n```bash\nnpm exec agent-browser -- --session memoryos-readme open http://localhost:5173/nodes\nnpm exec agent-browser -- --session memoryos-readme screenshot assets/screenshots/node-atlas-real.png\n```\n\nUse `agent-browser` screenshots to update README UI images.\n\n---\n\n## Troubleshooting\n\n### `npm run dev` starts on a different frontend port\n\nVite uses the next available port if `5173` is busy.\n\nLook at terminal output for the actual local URL.\n\n### Backend health returns 404\n\nUse:\n\n```text\nhttp://localhost:4400/api/health\n```\n\nThe health endpoint is under `/api`.\n\n### Redis unavailable warning appears\n\nRedis is optional for local development.\n\nThe backend continues without cache.\n\nStart Redis with:\n\n```bash\ndocker compose up -d redis\n```\n\n### Prisma client errors\n\nRun:\n\n```bash\nnpm run db:generate\n```\n\nThen run:\n\n```bash\nnpm run db:migrate\n```\n\n### Protected routes redirect to login\n\nSign in through:\n\n```text\n/auth/login\n```\n\nThe local demo auth flow creates `memoryos.session`.\n\n### Onboarding repeats\n\nComplete onboarding once.\n\nIt stores:\n\n```text\nmemoryos.onboarding\n```\n\nin browser localStorage.\n\n### API key fails\n\nCheck that:\n\n- the backend is running\n- the key starts with `mos_`\n- the key is active\n- the key has the needed scopes\n- the request includes `Authorization: Bearer`\n\n### Screenshots look logged out\n\nSeed a browser session before screenshot capture.\n\nExample:\n\n```bash\nnpm exec agent-browser -- --session memoryos-readme eval \"localStorage.setItem('memoryos.session', JSON.stringify({email:'demo@memoryos.local', name:'Archive Operator', remember:true, createdAt:new Date().toISOString()})); localStorage.setItem('memoryos.onboarding', JSON.stringify({completedAt:new Date().toISOString()}));\"\n```\n\n---\n\n## Documentation Map\n\nPrimary docs:\n\n- [API](docs/API.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Deployment](docs/DEPLOYMENT.md)\n- [GitHub Workflow](docs/GITHUB.md)\n- [Release Notes](docs/RELEASE.md)\n- [Security](SECURITY.md)\n\nProject process:\n\n- [Contributing](CONTRIBUTING.md)\n- [Changelog](CHANGELOG.md)\n- [License](LICENSE)\n\nRelease downloads:\n\n- [Site ZIP](release-artifacts/memoryos-site-v0.1.0.zip)\n- [Site SHA256](release-artifacts/memoryos-site-v0.1.0.zip.sha256)\n- [API ZIP](release-artifacts/memoryos-api-v0.1.0.zip)\n- [API SHA256](release-artifacts/memoryos-api-v0.1.0.zip.sha256)\n\nScreenshots:\n\n- [Node Atlas](assets/screenshots/node-atlas-real.png)\n- [Timeline](assets/screenshots/timeline-real.png)\n- [Developer Console](assets/screenshots/developer-console-real.png)\n\n---\n\n## GitHub Release Checklist\n\nBefore creating a GitHub Release:\n\n- Run `npm run typecheck`\n- Run `npm run lint`\n- Run `npm run build`\n- Confirm README screenshots are current\n- Confirm `release-artifacts` zip files exist\n- Confirm `.sha256` files exist\n- Confirm `CHANGELOG.md` is updated\n- Confirm `docs/RELEASE.md` is updated\n- Confirm API migrations are included\n- Confirm deployment docs are accurate\n\nSuggested release title:\n\n```text\nMemoryOS v0.1.0\n```\n\nSuggested release assets:\n\n```text\nmemoryos-site-v0.1.0.zip\nmemoryos-site-v0.1.0.zip.sha256\nmemoryos-api-v0.1.0.zip\nmemoryos-api-v0.1.0.zip.sha256\n```\n\nSuggested release summary:\n\n```text\nInitial MemoryOS release with cinematic spatial memory UI, Node Atlas, timeline rail, developer console, API key system, and deployable frontend/backend artifacts.\n```\n\n---\n\n## Development Philosophy\n\nMemoryOS should feel premium.\n\nIt should feel interactive.\n\nIt should feel useful.\n\nEvery route should render real content.\n\nEvery button should do something.\n\nEvery panel should have a purpose.\n\nThe system should avoid empty placeholder surfaces.\n\nThe product should stay realistic.\n\nIt should not rely on impossible AI claims.\n\nIt should use practical systems well.\n\nThe best version of MemoryOS is:\n\n- spatial\n- fast\n- cinematic\n- personal\n- inspectable\n- developer-friendly\n- emotionally engaging\n- operationally credible\n\n---\n\n## Current Limitations\n\nMemoryOS is still an early release.\n\nKnown limitations:\n\n- frontend auth uses local demo session behavior\n- backend JWT routes exist but are not fully wired to frontend auth state\n- uploads are local backend uploads, not object storage\n- Redis is optional locally and should be managed in production\n- Spotify support parses and embeds links but does not authenticate with Spotify OAuth\n- Web Audio generation is browser-based and intentionally lightweight\n- release zips do not include production `node_modules`\n\nThese are deliberate early-release tradeoffs.\n\nThey keep the project runnable and understandable.\n\n---\n\n## Roadmap Ideas\n\nPossible next releases:\n\n- backend-backed frontend auth session\n- API documentation site\n- database seed command\n- object storage adapter\n- richer media previews\n- real Spotify OAuth integration\n- graph virtualization improvements\n- advanced timeline playback\n- import/export UI\n- signed upload URLs\n- API usage analytics\n- webhook delivery retries\n- more release automation\n- Playwright regression suite\n- production observability\n\n---\n\n## Contributing\n\nRead:\n\n[CONTRIBUTING.md](CONTRIBUTING.md)\n\nBefore contributing:\n\n```bash\nnpm install\nnpm run typecheck\nnpm run lint\nnpm run build\n```\n\nUse small focused changes.\n\nKeep the interface cohesive.\n\nAvoid adding dead buttons.\n\nAvoid adding placeholder routes.\n\nPrefer existing components.\n\nPrefer shared visual language.\n\nKeep the app dark-mode first.\n\nKeep performance in mind.\n\n---\n\n## License\n\nMemoryOS is released under the MIT License.\n\nSee:\n\n[LICENSE](LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagnexis%2Fmemory-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagnexis%2Fmemory-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagnexis%2Fmemory-os/lists"}