@shahmilsaari/memory-core 0.1.0

package/README.md

@@ -0,0 +1,538 @@
+# @archmind/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.
+
+---
+
+## 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
+```
+
+---
+
+## Supported agents
+
+| Agent | File generated |
+|-------|---------------|
+| 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` |
+| Aider | `.aider.conf.yml` |
+| Continue.dev | `.continue/config.json` |
+| Devin | `DEVIN.md` |
+| Amazon Q | `.amazonq/dev/guidelines.md` |
+| Gemini Code Assist | `.gemini/styleguide.md` |
+| Zed AI | `.zed/settings.json` |
+| JetBrains AI | `.idea/ai-instructions.md` |
+
+Plus: `AGENTS.md`, `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)
+
+---
+
+## 1. PostgreSQL setup
+
+### macOS (Homebrew)
+
+```bash
+brew install postgresql@16
+brew services start postgresql@16
+```
+
+Verify it is running:
+
+```bash
+psql -U $(whoami) -l
+```
+
+### Linux (Ubuntu/Debian)
+
+```bash
+sudo apt install postgresql postgresql-contrib
+sudo systemctl start postgresql
+```
+
+### Windows
+
+Download and install 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:
+
+```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)
+
+```bash
+brew install pgvector
+```
+
+### Linux (Ubuntu/Debian)
+
+```bash
+sudo apt install postgresql-16-pgvector
+# Replace 16 with your PostgreSQL version
+```
+
+### Verify pgvector is installed
+
+```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
+
+```bash
+brew install ollama
+brew services start ollama
+```
+
+### 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
+
+```bash
+ollama pull nomic-embed-text
+```
+
+Verify Ollama is running:
+
+```bash
+curl http://localhost:11434
+# Expected: "Ollama is running"
+```
+
+---
+
+## 4. Create the database
+
+```bash
+createdb memory_core
+```
+
+Then run the setup SQL to create the table and indexes:
+
+```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
+
+```bash
+npm install -g @archmind/memory-core
+memory-core init
+```
+
+### Or clone and run locally (development)
+
+```bash
+git clone https://github.com/your-org/memory-core.git
+cd memory-core
+npm install
+npm run build
+node dist/cli.js init
+```
+
+---
+
+## 6. Configure environment
+
+Create a `.env` file in the project root (or `.memory-core.env` for per-project config):
+
+```env
+DATABASE_URL=postgresql://YOUR_USERNAME@localhost:5432/memory_core
+OLLAMA_URL=http://localhost:11434
+OLLAMA_MODEL=nomic-embed-text
+```
+
+Replace `YOUR_USERNAME` with your system username. On macOS with Homebrew, this is typically your macOS username with no password.
+
+To find your username:
+
+```bash
+whoami
+```
+
+---
+
+## Commands
+
+### `init` — Set up a project
+
+Run once inside any Git project:
+
+```bash
+cd /path/to/your-project
+npx @archmind/memory-core init
+```
+
+You will be asked:
+
+```
+Project name?           → my-api
+Architecture?           → Clean Architecture
+Language/framework?     → TypeScript / NestJS
+Pull relevant memories? → yes
+Install caveman?        → no
+Generate AI files?      → yes
+```
+
+This creates all AI agent config files in the project and saves `.memory-core.json` to remember your choices.
+
+---
+
+### `sync` — Refresh AI files
+
+After adding new memories, regenerate all agent files:
+
+```bash
+npx @archmind/memory-core sync
+```
+
+Pulls the latest relevant memories from the database and rewrites all generated files.
+
+---
+
+### `remember` — Save a decision
+
+```bash
+npx @archmind/memory-core remember "Controllers must only validate input and call use cases"
+```
+
+With options:
+
+```bash
+npx @archmind/memory-core remember "Use DTOs for all API responses" \
+  --type rule \
+  --scope global \
+  --tags "api,dto,response"
+```
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `--type` | `decision`, `rule`, `pattern`, `note` | `decision` |
+| `--scope` | `global`, `project` | `project` |
+| `--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`.
+
+```bash
+npx @archmind/memory-core global
+```
+
+With architecture filter:
+
+```bash
+npx @archmind/memory-core global --arch clean-architecture
+```
+
+**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.
+
+---
+
+### `search` — Find past decisions
+
+```bash
+npx @archmind/memory-core search "auth architecture"
+```
+
+With limit:
+
+```bash
+npx @archmind/memory-core search "database access" --limit 10
+```
+
+---
+
+## Architecture profiles
+
+Choose from six built-in profiles during `init`:
+
+| 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 |
+
+---
+
+## 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:
+
+| Level | Style |
+|-------|-------|
+| `lite` | Professional terseness |
+| `full` | Caveman mode (default) |
+| `ultra` | Telegraphic, minimum words |
+
+caveman rules are injected into every generated agent file automatically.
+
+---
+
+## Typical workflow
+
+### New project
+
+```bash
+git clone https://github.com/your-org/new-api.git
+cd new-api
+npx @archmind/memory-core init
+```
+
+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"
+```
+
+### Sync all projects after saving new decisions
+
+```bash
+npx @archmind/memory-core sync
+```
+
+### Search before making an architectural decision
+
+```bash
+npx @archmind/memory-core search "error handling strategy"
+```
+
+---
+
+## 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
+```
+
+---
+
+## Database schema
+
+```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()
+);
+```
+
+---
+
+## Troubleshooting
+
+### `extension "vector" is not available`
+
+pgvector is not installed for your PostgreSQL version. See [pgvector setup](#2-pgvector-setup) above.
+
+### `Cannot reach Ollama at http://localhost:11434`
+
+Ollama is not running. Start it:
+
+```bash
+brew services start ollama   # macOS
+ollama serve                 # Linux / manual
+```
+
+### `DATABASE_URL is not set`
+
+Create a `.env` file in the project root with your database URL. See [Configure environment](#6-configure-environment).
+
+### `createdb: error: database creation failed: ERROR: role does not exist`
+
+Your PostgreSQL user does not exist. Create it:
+
+```bash
+createuser -s $(whoami)
+```
+
+### Search returns fewer results than expected
+
+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.
+
+---
+
+## Development
+
+```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)
+```
+
+Run a command locally:
+
+```bash
+node dist/cli.js remember "my decision"
+node dist/cli.js search "query"
+```
+
+---
+
+## Publishing
+
+```bash
+npm login --scope=@archmind
+npm publish --access public
+```
+
+After publishing, anyone can use:
+
+```bash
+npx @archmind/memory-core init
+```
+
+---
+
+## License
+
+MIT