@shahmilsaari/memory-core 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shahmilsaari/memory-core",
+  "version": "0.1.0",
+  "description": "Universal AI memory core — generate AI context files from architecture profiles with RAG support",
+  "type": "module",
+  "bin": {
+    "memory-core": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "profiles"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^5.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "dotenv": "^16.4.0",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "ora": "^8.0.0",
+    "pg": "^8.11.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "@types/pg": "^8.11.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "memory",
+    "rag",
+    "architecture",
+    "copilot",
+    "cursor",
+    "claude",
+    "context"
+  ],
+  "license": "MIT"
+}

package/profiles/angular.yml

@@ -0,0 +1,33 @@
+name: angular
+displayName: Angular
+layer: frontend
+description: Angular with smart/dumb components, signals, standalone components, and OnPush
+
+rules:
+  - Use standalone components — no NgModules for new features
+  - Use Angular Signals for reactive state — prefer signals over RxJS for simple state
+  - Use OnPush change detection on all components — default is too expensive
+  - Follow smart/dumb component pattern — containers fetch data, presentational components render it
+  - Keep all HTTP calls inside services — never call HttpClient in components
+  - Use inject() function instead of constructor injection in modern Angular (v17+)
+  - Use the Angular Router with lazy-loaded routes for every feature
+  - Use reactive forms (FormBuilder) — never template-driven forms for complex forms
+  - Unsubscribe from observables using takeUntilDestroyed() or async pipe
+  - Use NgRx only for complex shared state — prefer component store or signals for local state
+
+folders:
+  - src/app/core
+  - src/app/shared/components
+  - src/app/shared/services
+  - src/app/features/<feature-name>/components
+  - src/app/features/<feature-name>/services
+  - src/app/features/<feature-name>/store
+  - src/app/layout
+
+avoid:
+  - NgModules for new features — use standalone components
+  - Default change detection — always set OnPush
+  - HTTP calls in components — use services
+  - Memory leaks from unsubscribed observables
+  - Logic in templates — move to component class
+  - God services with unrelated responsibilities

package/profiles/clean-architecture.yml

@@ -0,0 +1,33 @@
+name: clean-architecture
+displayName: Clean Architecture
+layer: backend
+description: Separation into domain, application, infrastructure, and interface layers
+
+rules:
+  - Entities encapsulate core business logic and have no external dependencies
+  - Use cases orchestrate application workflows and call domain entities
+  - Controllers must only validate input and delegate to use cases
+  - Infrastructure layer (DB, HTTP, queues) depends on application — never the reverse
+  - Domain layer must not import any framework or library code
+  - Use DTOs to transfer data across layer boundaries
+  - Repository interfaces are defined in the domain/application layer, implemented in infrastructure
+  - Validation happens at the interface/controller layer only
+
+folders:
+  - src/domain/entities
+  - src/domain/repositories
+  - src/domain/value-objects
+  - src/application/use-cases
+  - src/application/services
+  - src/application/dtos
+  - src/infrastructure/database
+  - src/infrastructure/http
+  - src/interfaces/controllers
+  - src/interfaces/presenters
+
+avoid:
+  - Business logic in controllers or route handlers
+  - Direct database queries inside use cases
+  - Framework-specific imports in the domain layer
+  - Calling use cases from other use cases directly
+  - Fat repositories that contain business logic

package/profiles/hexagonal.yml

@@ -0,0 +1,28 @@
+name: hexagonal
+displayName: Hexagonal Architecture
+layer: backend
+description: Ports and adapters — application core is isolated from all external systems
+
+rules:
+  - The application core defines ports (interfaces) for everything external
+  - Adapters implement ports — one adapter per external system (DB, HTTP, queue, etc.)
+  - The core must never instantiate or import adapters directly
+  - Dependency injection wires adapters to ports at startup
+  - All business logic lives inside the core/domain
+  - Driving adapters (HTTP, CLI, tests) call the core through primary ports
+  - Driven adapters (DB, email, payment) are called by the core through secondary ports
+
+folders:
+  - src/core/domain
+  - src/core/ports/inbound
+  - src/core/ports/outbound
+  - src/adapters/inbound/http
+  - src/adapters/inbound/cli
+  - src/adapters/outbound/database
+  - src/adapters/outbound/messaging
+
+avoid:
+  - Direct imports of adapter code inside the core
+  - Leaking infrastructure types into domain models
+  - Bypassing ports to call adapters directly
+  - Framework annotations inside domain classes

package/profiles/laravel-service-repository.yml

@@ -0,0 +1,32 @@
+name: laravel-service-repository
+displayName: Laravel Service Repository
+layer: backend
+description: Laravel with service and repository layers for business logic separation
+
+rules:
+  - Controllers are thin — validate request, call service, return response
+  - Services contain all business logic and orchestration
+  - Repositories abstract all Eloquent/database queries
+  - Repository interfaces are defined and bound via service container
+  - Use Form Requests for validation logic
+  - Use API Resources for response transformation
+  - Keep Eloquent models as data containers — relationships and casts only
+  - Events and listeners handle side effects (emails, notifications, cache)
+
+folders:
+  - app/Http/Controllers
+  - app/Http/Requests
+  - app/Http/Resources
+  - app/Services
+  - app/Repositories
+  - app/Repositories/Interfaces
+  - app/Models
+  - app/Events
+  - app/Listeners
+
+avoid:
+  - Business logic in controllers or models
+  - Raw DB queries in controllers
+  - Direct Eloquent calls inside services (use repositories)
+  - Logic inside Blade templates
+  - Fat models with business methods

package/profiles/modular-monolith.yml

@@ -0,0 +1,28 @@
+name: modular-monolith
+displayName: Modular Monolith
+layer: backend
+description: Self-contained feature modules with clear boundaries and no cross-module coupling
+
+rules:
+  - Each module owns its own data model, service, and controller
+  - Modules communicate only through public interfaces or events — never by importing internals
+  - Shared utilities live in a shared/ or common/ module
+  - Database tables are namespaced per module
+  - Each module can be extracted to a microservice independently
+  - Cross-module calls must go through a module's public API class
+  - No circular dependencies between modules
+
+folders:
+  - src/modules/<module-name>/controllers
+  - src/modules/<module-name>/services
+  - src/modules/<module-name>/repositories
+  - src/modules/<module-name>/dtos
+  - src/modules/<module-name>/entities
+  - src/shared/utils
+  - src/shared/types
+
+avoid:
+  - Importing private files from another module directly
+  - Shared mutable state between modules
+  - God services that span multiple module domains
+  - Circular module dependencies

package/profiles/mvc.yml

@@ -0,0 +1,27 @@
+name: mvc
+displayName: MVC
+layer: backend
+description: Model-View-Controller with thin controllers and fat models/services
+
+rules:
+  - Controllers handle HTTP only — parse input, call service, return response
+  - Models represent data and database schema
+  - Business logic lives in services, not controllers or models
+  - Views render output and contain no logic
+  - Services are testable independently of the HTTP layer
+  - Use a service layer between controllers and models
+  - Group files by feature, not by type (e.g. /users not /controllers)
+
+folders:
+  - src/controllers
+  - src/models
+  - src/services
+  - src/views
+  - src/middleware
+  - src/routes
+
+avoid:
+  - Logic in controllers beyond input parsing and response formatting
+  - Direct database calls in controllers
+  - Business rules inside model callbacks
+  - Fat controllers with inline queries

package/profiles/nextjs.yml

@@ -0,0 +1,32 @@
+name: nextjs
+displayName: Next.js App Router
+layer: fullstack
+description: Next.js 13+ App Router with server components, server actions, and colocation
+
+rules:
+  - Use Server Components by default — add 'use client' only when interactivity is required
+  - Data fetching happens in Server Components, not client hooks
+  - Use Server Actions for form mutations and data writes
+  - Keep page.tsx files thin — delegate to feature components
+  - Colocate components, hooks, and utilities near the route that uses them
+  - Shared UI lives in src/components/, shared logic in src/lib/
+  - API routes are for external integrations only — prefer Server Actions for internal mutations
+  - Use Route Groups to organize without affecting URL structure
+  - Environment variables exposed to client must be prefixed NEXT_PUBLIC_
+
+folders:
+  - app/(routes)
+  - app/api
+  - src/components/ui
+  - src/components/features
+  - src/lib/utils
+  - src/lib/actions
+  - src/lib/db
+  - src/types
+
+avoid:
+  - Data fetching in Client Components (use Server Components instead)
+  - useEffect for data loading
+  - Business logic inside page.tsx
+  - Mixing server and client code in the same file
+  - Exposing secrets via NEXT_PUBLIC_ variables

package/profiles/nuxt.yml

@@ -0,0 +1,32 @@
+name: nuxt
+displayName: Nuxt 3
+layer: fullstack
+description: Nuxt 3 with auto-imports, server routes, and composable-driven architecture
+
+rules:
+  - Use Nuxt auto-imports — no manual imports for composables, utils, or Vue APIs
+  - Use useFetch or useAsyncData for all data fetching — never axios or fetch directly in setup
+  - Use server/api/ routes for backend logic — keep business logic out of components
+  - Use useState for SSR-safe shared state — Pinia for complex global state
+  - Use definePageMeta for per-page middleware, layout, and head configuration
+  - Keep pages thin — delegate to feature components
+  - Use Nuxt plugins for third-party SDK initialization
+  - Use runtime config (useRuntimeConfig) for environment variables — never process.env in components
+
+folders:
+  - components/ui
+  - components/features
+  - composables
+  - server/api
+  - server/middleware
+  - pages
+  - layouts
+  - stores
+  - utils
+  - types
+
+avoid:
+  - Direct process.env access in components — use useRuntimeConfig
+  - Heavy logic in pages — delegate to composables and components
+  - Client-only libraries without <ClientOnly> wrapper or .client.ts suffix
+  - Mixing server and client code without clear separation

package/profiles/react-native.yml

@@ -0,0 +1,35 @@
+name: react-native
+displayName: React Native
+layer: frontend
+description: React Native with functional components, hooks, and mobile-first architecture
+
+rules:
+  - Use functional components with hooks — never class components
+  - Use React Navigation for all routing — never manipulate navigation stack manually
+  - Use React Query for server state — never useEffect for data fetching
+  - Use Zustand for global client state — Context only for theme and auth
+  - Separate business logic from UI — put in custom hooks or service files
+  - Use StyleSheet.create() for all styles — never inline style objects in JSX
+  - Memoize expensive list items with React.memo — FlatList performance depends on it
+  - Always provide keyExtractor on FlatList — never use index as key
+  - Handle loading and error states explicitly in every screen
+  - Use expo-secure-store for sensitive data — never AsyncStorage for tokens
+
+folders:
+  - src/screens
+  - src/components/ui
+  - src/components/features
+  - src/hooks
+  - src/store
+  - src/navigation
+  - src/services/api
+  - src/utils
+  - src/types
+
+avoid:
+  - Class components
+  - Inline style objects — use StyleSheet.create
+  - useEffect for data fetching — use React Query
+  - AsyncStorage for auth tokens — use secure storage
+  - Deep prop drilling — use global state
+  - ScrollView for long dynamic lists — use FlatList

package/profiles/react.yml

@@ -0,0 +1,37 @@
+name: react
+displayName: React
+layer: frontend
+description: Component-driven UI with functional components, hooks, and React Query
+
+rules:
+  - Use functional components only — never class components
+  - Extract all stateful and side-effect logic into custom hooks (use* prefix)
+  - Keep components under 150 lines — split into smaller focused components
+  - Co-locate state as close to where it is used as possible
+  - Lift state only when two or more siblings share the same data
+  - Use React Query or SWR for all server data fetching — never useEffect for data loading
+  - Use Zustand or Jotai for global client state — avoid large React Context for frequent updates
+  - Wrap async operations in useEffect with cleanup to prevent memory leaks
+  - Add Error Boundaries around major feature sections
+  - Lazy load route-level components with React.lazy + Suspense
+  - Never mutate state directly — always return new objects or arrays
+  - Memoize with React.memo, useMemo, useCallback only after profiling confirms a problem
+
+folders:
+  - src/components/ui
+  - src/components/features
+  - src/hooks
+  - src/store
+  - src/services/api
+  - src/pages
+  - src/utils
+  - src/types
+
+avoid:
+  - Class components
+  - Prop drilling beyond two levels — use context or global state
+  - Business logic inside JSX — move to hooks or service functions
+  - useEffect for data fetching on mount
+  - Array index as key in dynamic lists
+  - God components over 200 lines
+  - Inline style objects for non-dynamic values

package/profiles/svelte.yml

@@ -0,0 +1,29 @@
+name: svelte
+displayName: Svelte / SvelteKit
+layer: frontend
+description: Svelte 5 with runes, stores, and SvelteKit file-based routing
+
+rules:
+  - Use Svelte 5 runes ($state, $derived, $effect) for reactivity — avoid legacy reactive declarations
+  - Use $props() rune for component props with TypeScript types
+  - Use Svelte stores (writable, readable, derived) for shared state across components
+  - Keep components small and single-purpose — extract logic into .ts utility files
+  - Use SvelteKit load functions for data fetching — never fetch in onMount for SSR routes
+  - Use form actions for mutations — avoid manual fetch() for form submissions
+  - Co-locate component styles with scoped <style> blocks — no global CSS in components
+  - Use $effect sparingly — prefer derived state over side effects
+
+folders:
+  - src/lib/components/ui
+  - src/lib/components/features
+  - src/lib/stores
+  - src/lib/utils
+  - src/lib/types
+  - src/routes
+
+avoid:
+  - Legacy reactive declarations ($:) in new Svelte 5 code — use runes
+  - Fetching data in onMount for server-rendered pages — use load functions
+  - Global unscoped styles — use scoped <style> blocks
+  - Two-way binding on complex objects — keep data flow predictable
+  - Large components with mixed responsibilities

package/profiles/vue.yml

@@ -0,0 +1,35 @@
+name: vue
+displayName: Vue 3
+layer: frontend
+description: Vue 3 with Composition API, Pinia, and composable-driven architecture
+
+rules:
+  - Use Composition API with <script setup> — never Options API for new code
+  - Extract reusable logic into composables (use* prefix) in src/composables/
+  - Use Pinia for all global state — one store per domain (useUserStore, useCartStore)
+  - Use defineProps and defineEmits with full TypeScript types
+  - Follow props-down events-up pattern strictly — never mutate props
+  - Use Vue Router with lazy-loaded route components
+  - Use <Suspense> for async component loading
+  - Keep components under 200 lines — extract logic to composables
+  - Use v-model with defineModel() for two-way binding in child components
+  - Use provide/inject only for deeply nested component trees
+
+folders:
+  - src/components/ui
+  - src/components/features
+  - src/composables
+  - src/stores
+  - src/router
+  - src/views
+  - src/services
+  - src/utils
+  - src/types
+
+avoid:
+  - Options API in new components
+  - Mutating props directly — emit events instead
+  - Vuex — use Pinia
+  - Heavy logic inside templates
+  - Direct DOM manipulation — use template refs
+  - God components with mixed responsibilities

package/templates/AGENTS.md.hbs

@@ -0,0 +1,42 @@
+# AGENTS.md — {{projectName}}
+<!-- Generated by memory-core on {{generatedAt}} — run: memory-core sync -->
+
+**Type:** {{projectType}} | **Language:** {{language}}
+{{#if hasBackend}}**Backend:** {{backendArchitecture}}{{/if}}
+{{#if hasFrontend}}**Frontend:** {{frontendFramework}}{{/if}}
+
+---
+{{#if hasBackend}}
+## Backend Rules — {{backendArchitecture}}
+{{bullet backendRules}}
+
+### Structure
+{{bullet backendFolders}}
+
+### Never
+{{bullet backendAvoid}}
+{{/if}}
+{{#if hasFrontend}}
+
+## Frontend Rules — {{frontendFramework}}
+{{bullet frontendRules}}
+
+### Structure
+{{bullet frontendFolders}}
+
+### Never
+{{bullet frontendAvoid}}
+{{/if}}
+{{#if hasMemories}}
+
+---
+## Memory from Previous Projects
+{{#each memories}}
+- [{{type}}{{#if this.architecture}} · {{this.architecture}}{{/if}}] {{content}}
+{{/each}}
+{{/if}}
+{{#if caveman.enabled}}
+
+---
+Caveman ({{caveman.intensity}}): terse fragments only.
+{{/if}}

package/templates/AI_RULES.md.hbs

@@ -0,0 +1,39 @@
+# AI Rules — {{projectName}}
+<!-- Generated by memory-core on {{generatedAt}} -->
+
+These rules apply to ALL AI agents in this project.
+
+**Type:** {{projectType}} | **Language:** {{language}}
+{{#if hasBackend}}**Backend:** {{backendArchitecture}}{{/if}}
+{{#if hasFrontend}}**Frontend:** {{frontendFramework}}{{/if}}
+
+---
+{{#if hasBackend}}
+## Backend — {{backendArchitecture}}
+{{numbered backendRules}}
+
+**Avoid:**
+{{bullet backendAvoid}}
+{{/if}}
+{{#if hasFrontend}}
+
+## Frontend — {{frontendFramework}}
+{{numbered frontendRules}}
+
+**Avoid:**
+{{bullet frontendAvoid}}
+{{/if}}
+{{#if hasMemories}}
+
+---
+## Inherited Decisions
+{{#each memories}}
+{{@index}}. **[{{type}}]** {{content}}
+   {{#if tags.length}}_tags: {{join tags ", "}}_{{/if}}
+{{/each}}
+{{/if}}
+{{#if caveman.enabled}}
+
+---
+_Caveman {{caveman.intensity}} active — terse output only._
+{{/if}}

package/templates/ARCHITECTURE.md.hbs

@@ -0,0 +1,51 @@
+# Architecture — {{projectName}}
+<!-- Generated by memory-core on {{generatedAt}} -->
+
+**Type:** {{projectType}} | **Language:** {{language}}
+
+---
+{{#if hasBackend}}
+## Backend — {{backendArchitecture}}
+
+{{backendDescription}}
+
+### Rules
+{{numbered backendRules}}
+
+### Folder Structure
+```
+{{#each backendFolders}}
+{{this}}/
+{{/each}}
+```
+
+### Avoid
+{{bullet backendAvoid}}
+{{/if}}
+{{#if hasFrontend}}
+
+## Frontend — {{frontendFramework}}
+
+{{frontendDescription}}
+
+### Rules
+{{numbered frontendRules}}
+
+### Folder Structure
+```
+{{#each frontendFolders}}
+{{this}}/
+{{/each}}
+```
+
+### Avoid
+{{bullet frontendAvoid}}
+{{/if}}
+{{#if hasMemories}}
+
+---
+## Architectural Decisions
+{{#each memories}}
+> **[{{type}}]** {{content}}
+{{/each}}
+{{/if}}

package/templates/CLAUDE.md.hbs

@@ -0,0 +1,52 @@
+# CLAUDE.md
+<!-- Generated by memory-core on {{generatedAt}} — run: memory-core sync to refresh -->
+
+## Project
+**Name:** {{projectName}}
+**Type:** {{projectType}}
+**Language:** {{language}}
+{{#if hasBackend}}**Backend:** {{backendArchitecture}}{{/if}}
+{{#if hasFrontend}}**Frontend:** {{frontendFramework}}{{/if}}
+
+---
+{{#if hasBackend}}
+## Backend — {{backendArchitecture}}
+> {{backendDescription}}
+
+### Rules
+{{bullet backendRules}}
+
+### Structure
+{{bullet backendFolders}}
+
+### Avoid
+{{bullet backendAvoid}}
+{{/if}}
+{{#if hasFrontend}}
+
+## Frontend — {{frontendFramework}}
+> {{frontendDescription}}
+
+### Rules
+{{bullet frontendRules}}
+
+### Structure
+{{bullet frontendFolders}}
+
+### Avoid
+{{bullet frontendAvoid}}
+{{/if}}
+{{#if hasMemories}}
+
+---
+## Relevant Memories
+{{#each memories}}
+- [{{type}}] {{content}}{{#if tags.length}} _({{join tags ", "}})_{{/if}}
+{{/each}}
+{{/if}}
+{{#if caveman.enabled}}
+
+---
+## Token Optimization
+Caveman active ({{caveman.intensity}}). Terse fragments. No summaries unless asked.
+{{/if}}

package/templates/DEVIN.md.hbs

@@ -0,0 +1,26 @@
+# DEVIN.md — {{projectName}}
+<!-- Generated by memory-core on {{generatedAt}} -->
+
+## Architecture
+{{architecture}} — {{language}} / {{framework}}
+
+## Rules
+{{bullet rules}}
+
+## Structure
+{{bullet folders}}
+
+## Avoid
+{{bullet avoid}}
+{{#if hasMemories}}
+
+## Project Memory
+{{#each memories}}
+- [{{type}}] {{content}}
+{{/each}}
+{{/if}}
+{{#if caveman.enabled}}
+
+## Response Style
+Terse. Minimal. No padding. Caveman {{caveman.intensity}}.
+{{/if}}