@shahmilsaari/memory-core 0.1.0 → 0.1.1

package/README.md

@@ -1,19 +1,34 @@
-# @archmind/memory-core
+# @shahmilsaari/memory-core
 
-Universal AI memory core. Install in any Git project and every AI coding agent — Copilot, Cursor, Claude, Windsurf, Cline, and more — will automatically follow your architecture rules and past decisions.
+Universal AI memory for any project. Install once, and every AI coding agent — Copilot, Cursor, Claude Code, Windsurf, Cline, and 13 more — automatically follows your architecture rules, past decisions, and best practices. Backed by PostgreSQL + pgvector and fully local AI via Ollama. No OpenAI key required.
+
+```bash
+npx @shahmilsaari/memory-core init
+```
 
 ---
 
 ## How it works
 
 ```
-Your central PostgreSQL database (memories + rules)
-              ↓
-   memory-core init  (run once per project)
-              ↓
-   Generates AI config files for every agent
-              ↓
-   Every agent reads its file → follows your rules
+memory-core init
+      │
+      ├── You pick: Backend / Frontend / Fullstack
+      ├── You pick: Architecture (Clean, MVC, React, Vue, …)
+      │
+      ▼
+PostgreSQL + pgvector
+192 predefined rules — each with a WHY
++ your own saved decisions
+      │
+      ▼
+18 AI agent config files generated
+      │
+      ▼
+Every agent reads its file → follows your rules
+
+git commit → pre-commit hook → Ollama checks diff
+→ violations blocked with Rule + Why + Fix
 ```
 
 ---
@@ -21,10 +36,10 @@ Your central PostgreSQL database (memories + rules)
 ## Supported agents
 
 | Agent | File generated |
-|-------|---------------|
+|---|---|
+| Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 | Cursor | `.cursorrules` + `.cursor/rules/memory-core.mdc` |
-| Claude Code | `CLAUDE.md` |
 | Windsurf | `.windsurfrules` |
 | Cline | `.clinerules` |
 | Roo Code | `.roo/rules/memory-core.md` |
@@ -35,195 +50,155 @@ Your central PostgreSQL database (memories + rules)
 | Gemini Code Assist | `.gemini/styleguide.md` |
 | Zed AI | `.zed/settings.json` |
 | JetBrains AI | `.idea/ai-instructions.md` |
+| OpenHands / AGENTS | `AGENTS.md` |
 
-Plus: `AGENTS.md`, `AI_RULES.md`, `ARCHITECTURE.md`, `PROJECT_MEMORY.md`
+Plus: `AI_RULES.md`, `ARCHITECTURE.md`, `PROJECT_MEMORY.md`
 
 ---
 
 ## Prerequisites
 
-You need three things installed before using this package:
-
-1. **PostgreSQL** (local or remote)
-2. **pgvector** (PostgreSQL extension for semantic search)
-3. **Ollama** with `nomic-embed-text` model (free, local embeddings — no API key needed)
+| Requirement | Purpose |
+|---|---|
+| PostgreSQL 14+ | Memory storage |
+| pgvector | Semantic similarity search |
+| Ollama + `nomic-embed-text` | Free local embeddings (no API key) |
+| Ollama + `llama3.2` | Pre-commit rule checking |
 
 ---
 
-## 1. PostgreSQL setup
+## Setup
 
-### macOS (Homebrew)
+### 1. PostgreSQL
 
+**macOS**
 ```bash
 brew install postgresql@16
 brew services start postgresql@16
 ```
 
-Verify it is running:
-
-```bash
-psql -U $(whoami) -l
-```
-
-### Linux (Ubuntu/Debian)
-
+**Linux**
 ```bash
 sudo apt install postgresql postgresql-contrib
 sudo systemctl start postgresql
 ```
 
-### Windows
-
-Download and install from [postgresql.org](https://www.postgresql.org/download/windows/).
+**Windows** — download from [postgresql.org](https://www.postgresql.org/download/windows/)
 
 ---
 
-## 2. pgvector setup
-
-pgvector adds vector similarity search to PostgreSQL. It must be built for your exact PostgreSQL version.
-
-### macOS with PostgreSQL@16 (Homebrew)
-
-The brew pgvector package targets pg17+, so build from source:
+### 2. pgvector
 
+**macOS with PostgreSQL@16** (brew pgvector only targets pg17+, build from source):
 ```bash
-# Install build tools if needed
 xcode-select --install
-
-# Clone and build for PostgreSQL@16
 git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git /tmp/pgvector
 cd /tmp/pgvector
 make PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config
 make install PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config
 ```
 
-### macOS with PostgreSQL@17+ (Homebrew)
-
+**macOS with PostgreSQL@17+**
 ```bash
 brew install pgvector
 ```
 
-### Linux (Ubuntu/Debian)
-
+**Linux**
 ```bash
-sudo apt install postgresql-16-pgvector
-# Replace 16 with your PostgreSQL version
+sudo apt install postgresql-16-pgvector   # replace 16 with your version
 ```
 
-### Verify pgvector is installed
-
+Verify:
 ```bash
 psql -U $(whoami) -c "SELECT * FROM pg_available_extensions WHERE name = 'vector';"
 ```
 
-You should see a row with `name = vector`.
-
 ---
 
-## 3. Ollama setup
-
-Ollama runs the embedding model locally. No API key or internet connection required after setup.
-
-### macOS
+### 3. Ollama
 
+**macOS**
 ```bash
 brew install ollama
 brew services start ollama
 ```
 
-### Linux
-
+**Linux**
 ```bash
 curl -fsSL https://ollama.com/install.sh | sh
 ollama serve &
 ```
 
-### Windows
-
-Download from [ollama.com](https://ollama.com/download).
-
-### Pull the embedding model
+**Windows** — download from [ollama.com](https://ollama.com/download)
 
+Pull the required models:
 ```bash
-ollama pull nomic-embed-text
-```
-
-Verify Ollama is running:
-
-```bash
-curl http://localhost:11434
-# Expected: "Ollama is running"
+ollama pull nomic-embed-text   # embeddings — used by remember/search/sync
+ollama pull llama3.2           # code analysis — used by pre-commit hook
 ```
 
 ---
 
-## 4. Create the database
+### 4. Create the database
 
 ```bash
 createdb memory_core
 ```
 
-Then run the setup SQL to create the table and indexes:
-
+Then run the schema (get `setup.sql` from the repo or copy below):
 ```bash
 psql -U $(whoami) -d memory_core -f setup.sql
 ```
 
-Expected output:
-
-```
-CREATE EXTENSION
-CREATE TABLE
-CREATE INDEX
-CREATE INDEX
-CREATE INDEX
-```
-
----
-
-## 5. Install the package
-
-### Use without installing (recommended)
-
-```bash
-npx @archmind/memory-core init
-```
-
-### Or install globally
+`setup.sql` contents:
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
 
-```bash
-npm install -g @archmind/memory-core
-memory-core init
-```
+CREATE TABLE IF NOT EXISTS memories (
+  id           BIGSERIAL PRIMARY KEY,
+  type         TEXT NOT NULL,
+  scope        TEXT NOT NULL DEFAULT 'project',
+  architecture TEXT,
+  project_name TEXT,
+  title        TEXT,
+  content      TEXT NOT NULL,
+  reason       TEXT,
+  tags         TEXT[] DEFAULT '{}',
+  embedding    vector(768),
+  created_at   TIMESTAMP DEFAULT now()
+);
 
-### Or clone and run locally (development)
+CREATE INDEX IF NOT EXISTS memories_embedding_idx
+  ON memories USING ivfflat (embedding vector_cosine_ops)
+  WITH (lists = 100);
 
-```bash
-git clone https://github.com/your-org/memory-core.git
-cd memory-core
-npm install
-npm run build
-node dist/cli.js init
+CREATE INDEX IF NOT EXISTS memories_architecture_idx ON memories (architecture);
+CREATE INDEX IF NOT EXISTS memories_scope_idx ON memories (scope);
 ```
 
 ---
 
-## 6. Configure environment
+### 5. Configure environment
 
-Create a `.env` file in the project root (or `.memory-core.env` for per-project config):
+Create `.env` in the project where you run memory-core (or `.memory-core.env` per project):
 
 ```env
 DATABASE_URL=postgresql://YOUR_USERNAME@localhost:5432/memory_core
 OLLAMA_URL=http://localhost:11434
 OLLAMA_MODEL=nomic-embed-text
+OLLAMA_CHAT_MODEL=llama3.2
 ```
 
-Replace `YOUR_USERNAME` with your system username. On macOS with Homebrew, this is typically your macOS username with no password.
+Find your username: `whoami`
+
+---
 
-To find your username:
+### 6. Seed the database
+
+Load 192 predefined best-practice rules (each with a reason explaining why it exists):
 
 ```bash
-whoami
+npx @shahmilsaari/memory-core seed
 ```
 
 ---
@@ -232,304 +207,256 @@ whoami
 
 ### `init` — Set up a project
 
-Run once inside any Git project:
-
 ```bash
-cd /path/to/your-project
-npx @archmind/memory-core init
+cd your-project
+npx @shahmilsaari/memory-core init
 ```
 
-You will be asked:
-
+Interactive prompts:
 ```
-Project name?           → my-api
-Architecture?           → Clean Architecture
-Language/framework?     → TypeScript / NestJS
-Pull relevant memories? → yes
-Install caveman?        → no
-Generate AI files?      → yes
+Project name?         → my-api
+Project type?         → Backend / Frontend / Fullstack
+Backend architecture? → Clean Architecture
+Frontend framework?   → (skipped for backend-only)
+Language?             → TypeScript
+Install caveman?      → no
 ```
 
-This creates all AI agent config files in the project and saves `.memory-core.json` to remember your choices.
+Generates all 18 agent config files and saves `.memory-core.json`.
 
 ---
 
-### `sync` — Refresh AI files
-
-After adding new memories, regenerate all agent files:
+### `sync` — Regenerate all agent files
 
 ```bash
-npx @archmind/memory-core sync
+npx @shahmilsaari/memory-core sync
 ```
 
-Pulls the latest relevant memories from the database and rewrites all generated files.
+Re-pulls memories from the DB and rewrites all 18 files. Run after `remember` or `seed`.
 
 ---
 
 ### `remember` — Save a decision
 
 ```bash
-npx @archmind/memory-core remember "Controllers must only validate input and call use cases"
+npx @shahmilsaari/memory-core remember "Controllers must never call the database directly"
 ```
 
-With options:
+Prompts: _"Why does this rule exist?"_ — the reason is stored and shown to agents and developers when a violation is caught.
 
+With flags:
 ```bash
-npx @archmind/memory-core remember "Use DTOs for all API responses" \
+npx @shahmilsaari/memory-core remember "Use DTOs for all API responses" \
   --type rule \
   --scope global \
+  --reason "Raw DB entities leak internal schema and expose sensitive fields to clients" \
   --tags "api,dto,response"
 ```
 
-| Option | Values | Default |
-|--------|--------|---------|
-| `--type` | `decision`, `rule`, `pattern`, `note` | `decision` |
-| `--scope` | `global`, `project` | `project` |
+| Flag | Values | Default |
+|---|---|---|
+| `--type` | `decision` `rule` `pattern` `note` | `decision` |
+| `--scope` | `global` `project` | `project` |
+| `--reason` | free text | prompted interactively |
 | `--tags` | comma-separated | none |
 
 ---
 
-### `global` — Sync memory to every AI agent globally
-
-Injects your memories into the global config of **every AI agent** — so all of them follow your rules in every project, without running `init`.
+### `search` — Semantic search
 
 ```bash
-npx @archmind/memory-core global
+npx @shahmilsaari/memory-core search "error handling"
+npx @shahmilsaari/memory-core search "auth strategy" --limit 10
 ```
 
-With architecture filter:
+---
+
+### `seed` — Load predefined rules
 
 ```bash
-npx @archmind/memory-core global --arch clean-architecture
+npx @shahmilsaari/memory-core seed
+npx @shahmilsaari/memory-core seed --arch clean-architecture   # one architecture only
+npx @shahmilsaari/memory-core seed --force                     # re-seed existing entries
 ```
 
-**What gets updated:**
-
-| Agent | Global file written |
-|-------|-------------------|
-| Claude Code | `~/.claude/CLAUDE.md` |
-| GitHub Copilot | VS Code `settings.json` → `github.copilot.chat.codeGeneration.instructions` |
-| Cursor | `~/.cursor/rules/memory-core.mdc` |
-| Cline | VS Code `settings.json` → `cline.customInstructions` |
-| Continue.dev | `~/.continue/config.json` → `systemMessage` |
-| Aider | `~/.aider.conf.yml` |
-| Zed AI | `~/.config/zed/settings.json` → `assistant.system_prompt` |
-| Windsurf | `~/.windsurf/rules/memory-core.md` |
-
-Run this again after `memory-core remember` to keep all agents in sync.
+192 rules across all architectures. Every rule includes a `reason` explaining why it exists.
 
 ---
 
-### `search` — Find past decisions
+### `hook install` — Pre-commit enforcement
 
 ```bash
-npx @archmind/memory-core search "auth architecture"
+npx @shahmilsaari/memory-core hook install
 ```
 
-With limit:
+Installs a git pre-commit hook. Every `git commit` automatically checks staged source files against your architecture rules using Ollama (llama3.2). Violations are blocked with full context:
 
-```bash
-npx @archmind/memory-core search "database access" --limit 10
 ```
+  ✗ 2 rule violations found — commit blocked
 
----
+  [1] src/controllers/user.ts:32
+      Rule:   Thin controllers — business logic belongs in services
+      Why:    Logic in controllers cannot be reused from CLI, queues, or other
+              entry points — it gets siloed and duplicated across handlers
+      Issue:  Password validation logic inside route handler
+      Fix:    Move to UserService.validateCredentials()
 
-## Architecture profiles
+  [2] src/domain/user.entity.ts:5
+      Rule:   Domain has zero external imports
+      Why:    Framework imports in the domain layer tie business logic to
+              infrastructure — you can't swap the DB or test without spinning up the stack
+      Issue:  Imports 'typeorm' directly
+      Fix:    Define IUserRepository interface in domain, implement in infrastructure/
 
-Choose from six built-in profiles during `init`:
+  To bypass (not recommended): git commit --no-verify
+  To save as memory: memory-core remember "<lesson>"
+```
 
-| Profile | Best for |
-|---------|----------|
-| **Clean Architecture** | Domain-driven APIs with strict layer separation |
-| **Modular Monolith** | Feature-based modules that could become microservices |
-| **MVC** | Standard web apps with controllers, models, services |
-| **Hexagonal Architecture** | Port/adapter isolation, highly testable cores |
-| **Next.js App Router** | Next.js 13+ with server components and server actions |
-| **Laravel Service Repository** | Laravel APIs with service and repository pattern |
+```bash
+npx @shahmilsaari/memory-core hook uninstall   # remove the hook
+```
 
 ---
 
-## Caveman token saver (optional)
-
-During `init` you can enable [caveman](https://github.com/juliusbrussee/caveman), which compresses AI responses by 65–75% while keeping them accurate.
-
-Choose intensity:
+### `check` — Manual rule check
 
-| Level | Style |
-|-------|-------|
-| `lite` | Professional terseness |
-| `full` | Caveman mode (default) |
-| `ultra` | Telegraphic, minimum words |
+```bash
+npx @shahmilsaari/memory-core check --staged           # check staged files
+npx @shahmilsaari/memory-core check --staged --verbose # show model + diff details
+```
 
-caveman rules are injected into every generated agent file automatically.
+Same as the pre-commit hook — useful in CI/CD pipelines.
 
 ---
 
-## Typical workflow
+### `global` — Sync to all agents globally
 
-### New project
+Writes your rules to the global config of every installed agent — so they follow your rules in every project without running `init`:
 
 ```bash
-git clone https://github.com/your-org/new-api.git
-cd new-api
-npx @archmind/memory-core init
+npx @shahmilsaari/memory-core global
 ```
 
-Every AI agent in this project now follows your architecture rules.
-
-### Save a new decision mid-project
-
-```bash
-npx @archmind/memory-core remember "Auth tokens must be validated in middleware, never in controllers" \
-  --type decision \
-  --scope global \
-  --tags "auth,middleware"
-```
+| Agent | Global file |
+|---|---|
+| Claude Code | `~/.claude/CLAUDE.md` |
+| GitHub Copilot | VS Code `settings.json` |
+| Cursor | `~/.cursor/rules/memory-core.mdc` |
+| Cline | VS Code `settings.json` |
+| Continue.dev | `~/.continue/config.json` |
+| Aider | `~/.aider.conf.yml` |
+| Zed AI | `~/.config/zed/settings.json` |
+| Windsurf | `~/.windsurf/rules/memory-core.md` |
 
-### Sync all projects after saving new decisions
+---
 
-```bash
-npx @archmind/memory-core sync
-```
+## Architecture profiles
 
-### Search before making an architectural decision
+### Backend
+| Profile | Best for |
+|---|---|
+| **Clean Architecture** | Domain-driven APIs, strict layer separation |
+| **Modular Monolith** | Feature modules that could become microservices |
+| **MVC** | Standard web apps, controllers + services |
+| **Hexagonal** | Port/adapter isolation, highly testable cores |
+| **Next.js** | Next.js 13+ fullstack (server components + actions) |
+| **Laravel** | Laravel APIs with service-repository pattern |
+
+### Frontend
+| Profile | Best for |
+|---|---|
+| **React** | Functional components, hooks, React Query, Zustand |
+| **Vue 3** | Composition API, Pinia, composables |
+| **Angular** | Standalone components, signals, OnPush |
+| **Svelte** | Svelte 5 runes, SvelteKit load functions |
+| **Nuxt 3** | Fullstack Vue with SSR, server routes |
+| **React Native** | Mobile apps, FlatList, secure storage |
 
-```bash
-npx @archmind/memory-core search "error handling strategy"
-```
+Fullstack projects get dual sections — one for backend, one for frontend — in every generated agent file.
 
 ---
 
-## Project structure
-
-```
-memory-core/
-  src/
-    cli.ts              ← CLI entry point (init, sync, remember, search)
-    config.ts           ← Environment config loader
-    db.ts               ← PostgreSQL connection + memory CRUD
-    embedding.ts        ← Ollama embedding calls
-    retriever.ts        ← Semantic search via pgvector
-    generator.ts        ← Profile loader + Handlebars renderer + file writer
-    project-detector.ts ← Auto-detect language/framework from project files
-
-  profiles/             ← Architecture profile YAML files
-    clean-architecture.yml
-    modular-monolith.yml
-    mvc.yml
-    hexagonal.yml
-    nextjs.yml
-    laravel-service-repository.yml
-
-  templates/            ← Handlebars templates for each AI agent
-    CLAUDE.md.hbs
-    copilot-instructions.md.hbs
-    cursorrules.hbs
-    cursor-rule.mdc.hbs
-    windsurfrules.hbs
-    clinerules.hbs
-    roo-rule.md.hbs
-    aider.conf.yml.hbs
-    continue-config.json.hbs
-    DEVIN.md.hbs
-    amazonq-guidelines.md.hbs
-    gemini-styleguide.md.hbs
-    zed-settings.json.hbs
-    jetbrains-ai.md.hbs
-    AGENTS.md.hbs
-    AI_RULES.md.hbs
-    ARCHITECTURE.md.hbs
-    PROJECT_MEMORY.md.hbs
-
-  setup.sql             ← PostgreSQL schema (run once)
-  .env.example          ← Environment variable template
-```
-
----
+## Caveman token saver (optional)
 
-## Database schema
+Compresses AI responses 65–75% by stripping filler words. Enabled optionally during `init`. Injected into every agent file automatically.
 
-```sql
-CREATE TABLE memories (
-  id           BIGSERIAL PRIMARY KEY,
-  type         TEXT NOT NULL,           -- decision | rule | pattern | note
-  scope        TEXT NOT NULL,           -- global | project
-  architecture TEXT,                    -- clean-architecture | mvc | etc.
-  project_name TEXT,
-  title        TEXT,
-  content      TEXT NOT NULL,
-  tags         TEXT[],
-  embedding    vector(768),             -- nomic-embed-text output
-  created_at   TIMESTAMP DEFAULT now()
-);
-```
+| Level | Style |
+|---|---|
+| `lite` | Professional terseness |
+| `full` | Caveman mode |
+| `ultra` | Telegraphic, minimum words |
 
 ---
 
-## Troubleshooting
+## Typical workflow
 
-### `extension "vector" is not available`
+```bash
+# New project
+cd my-api
+npx @shahmilsaari/memory-core init
+npx @shahmilsaari/memory-core hook install
 
-pgvector is not installed for your PostgreSQL version. See [pgvector setup](#2-pgvector-setup) above.
+# Save a decision mid-project
+npx @shahmilsaari/memory-core remember "All auth goes through middleware, never duplicated in controllers" \
+  --type decision --scope global
 
-### `Cannot reach Ollama at http://localhost:11434`
+# Sync agent files after new decisions
+npx @shahmilsaari/memory-core sync
 
-Ollama is not running. Start it:
+# Search before making an architectural decision
+npx @shahmilsaari/memory-core search "caching strategy"
 
-```bash
-brew services start ollama   # macOS
-ollama serve                 # Linux / manual
+# Try to commit code that breaks rules → hook blocks it with explanation
+git commit -m "add user endpoint"
 ```
 
-### `DATABASE_URL is not set`
+---
 
-Create a `.env` file in the project root with your database URL. See [Configure environment](#6-configure-environment).
+## Environment variables
 
-### `createdb: error: database creation failed: ERROR: role does not exist`
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
+| `OLLAMA_URL` | No | `http://localhost:11434` | Ollama server URL |
+| `OLLAMA_MODEL` | No | `nomic-embed-text` | Embedding model |
+| `OLLAMA_CHAT_MODEL` | No | `llama3.2` | Chat model for pre-commit checks |
 
-Your PostgreSQL user does not exist. Create it:
+---
 
-```bash
-createuser -s $(whoami)
-```
+## Troubleshooting
 
-### Search returns fewer results than expected
+**`extension "vector" is not available`**
+pgvector not installed for your PostgreSQL version. See [pgvector setup](#2-pgvector-setup).
 
-This is normal when the database has fewer than 100 memories. The ivfflat index is optimized for large datasets. Results improve as you add more memories.
+**`Ollama not running — skipping rule check`**
+Start Ollama: `brew services start ollama` (macOS) or `ollama serve` (Linux).
 
----
+**`Chat model "llama3.2" not found`**
+Pull the model: `ollama pull llama3.2`. Or set `OLLAMA_CHAT_MODEL=mistral` in `.env`.
 
-## Development
+**`DATABASE_URL is not set`**
+Create `.env` in your project root. See [Configure environment](#5-configure-environment).
 
+**`createdb: role does not exist`**
 ```bash
-git clone https://github.com/your-org/memory-core.git
-cd memory-core
-npm install
-npm run build        # compile TypeScript → dist/
-npm run dev          # run with tsx (no build needed)
+createuser -s $(whoami)
 ```
 
-Run a command locally:
-
-```bash
-node dist/cli.js remember "my decision"
-node dist/cli.js search "query"
-```
+**Pre-commit hook flagging config/JSON files**
+The hook only checks source files (`.ts .tsx .js .jsx .py .php .rb .go .java .cs .swift .kt .rs .vue .svelte`). Config and env files are automatically skipped.
 
 ---
 
-## Publishing
-
-```bash
-npm login --scope=@archmind
-npm publish --access public
-```
-
-After publishing, anyone can use:
+## Roadmap
 
-```bash
-npx @archmind/memory-core init
-```
+| Feature | Description |
+|---|---|
+| CI/CD check | GitHub Actions workflow — fails PRs that violate rules |
+| Watch mode | `memory-core watch` — checks files on save in real-time |
+| Violation memory | Auto-save caught violations as "never do X, do Y" memories |
+| Rule analytics | Track which rules break most, which files are worst offenders |
+| Team sync | `memory-core push/pull` — shared memory pool across the whole team |
+| Memory review | `memory-core approve` — team sign-off before rules propagate |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shahmilsaari/memory-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Universal AI memory core — generate AI context files from architecture profiles with RAG support",
   "type": "module",
   "bin": {