@shahmilsaari/memory-core

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.

npx @shahmilsaari/memory-core init

How it works

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

Supported agents

Plus: AI_RULES.md, ARCHITECTURE.md, PROJECT_MEMORY.md

Prerequisites

Setup

1. PostgreSQL

macOS

brew install postgresql@16
brew services start postgresql@16

Linux

sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

Windows — download from postgresql.org

2. pgvector

macOS with PostgreSQL@16 (brew pgvector only targets pg17+, build from source):

xcode-select --install
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+

brew install pgvector

Linux

sudo apt install postgresql-16-pgvector   # replace 16 with your version

Verify:

psql -U $(whoami) -c "SELECT * FROM pg_available_extensions WHERE name = 'vector';"

3. Ollama

macOS

brew install ollama
brew services start ollama

Linux

curl -fsSL https://ollama.com/install.sh | sh
ollama serve &

Windows — download from ollama.com

Pull the required models:

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

createdb memory_core

Then run the schema (get setup.sql from the repo or copy below):

psql -U $(whoami) -d memory_core -f setup.sql

setup.sql contents:

CREATE EXTENSION IF NOT EXISTS vector;

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()
);

CREATE INDEX IF NOT EXISTS memories_embedding_idx
  ON memories USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);

CREATE INDEX IF NOT EXISTS memories_architecture_idx ON memories (architecture);
CREATE INDEX IF NOT EXISTS memories_scope_idx ON memories (scope);

5. Configure environment

Create .env in the project where you run memory-core (or .memory-core.env per project):

DATABASE_URL=postgresql://YOUR_USERNAME@localhost:5432/memory_core
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=nomic-embed-text
OLLAMA_CHAT_MODEL=llama3.2

Find your username: whoami

6. Seed the database

Load 192 predefined best-practice rules (each with a reason explaining why it exists):

npx @shahmilsaari/memory-core seed

Commands

init — Set up a project

cd your-project
npx @shahmilsaari/memory-core init

Interactive prompts:

Project name?         → my-api
Project type?         → Backend / Frontend / Fullstack
Backend architecture? → Clean Architecture
Frontend framework?   → (skipped for backend-only)
Language?             → TypeScript
Install caveman?      → no

Generates all 18 agent config files and saves .memory-core.json.

sync — Regenerate all agent files

npx @shahmilsaari/memory-core sync

Re-pulls memories from the DB and rewrites all 18 files. Run after remember or seed.

remember — Save a decision

npx @shahmilsaari/memory-core remember "Controllers must never call the database directly"

Prompts: "Why does this rule exist?" — the reason is stored and shown to agents and developers when a violation is caught.

With flags:

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"

search — Semantic search

npx @shahmilsaari/memory-core search "error handling"
npx @shahmilsaari/memory-core search "auth strategy" --limit 10

seed — Load predefined rules

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

192 rules across all architectures. Every rule includes a reason explaining why it exists.

hook install — Pre-commit enforcement

npx @shahmilsaari/memory-core hook install

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:

  ✗ 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()

  [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/

  To bypass (not recommended): git commit --no-verify
  To save as memory: memory-core remember "<lesson>"

npx @shahmilsaari/memory-core hook uninstall   # remove the hook

watch — Real-time rule checking

npx @shahmilsaari/memory-core watch

Runs in your terminal and checks every source file as you save it. Violations print immediately — no commit needed.

  archmind watch — real-time rule enforcement

  watching: /your/project
  model:    llama3.2
  rules:    24
  ctrl+c to stop

  [10:42:11] saved: src/controllers/user.ts

  ✗ 1 violation in src/controllers/user.ts

  [1] src/controllers/user.ts:34
      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 hashing inside the route handler
      Fix:    Move to UserService.hashPassword()

  Fix violations or run: memory-core remember "<lesson>"

Options:

npx @shahmilsaari/memory-core watch --path src/      # watch a specific directory
npx @shahmilsaari/memory-core watch --verbose        # show diff size and model details

Ignores: node_modules, dist, build, .git, config files — only checks source code.

check — Manual rule check

npx @shahmilsaari/memory-core check --staged           # check staged files
npx @shahmilsaari/memory-core check --staged --verbose # show model + diff details

Same as the pre-commit hook — useful in CI/CD pipelines.

global — Sync to all agents globally

Writes your rules to the global config of every installed agent — so they follow your rules in every project without running init:

npx @shahmilsaari/memory-core global

Architecture profiles

Backend

Frontend

Fullstack projects get dual sections — one for backend, one for frontend — in every generated agent file.

Caveman token saver (optional)

Compresses AI responses 65–75% by stripping filler words. Enabled optionally during init. Injected into every agent file automatically.

Typical workflow

# New project
cd my-api
npx @shahmilsaari/memory-core init
npx @shahmilsaari/memory-core hook install

# Save a decision mid-project
npx @shahmilsaari/memory-core remember "All auth goes through middleware, never duplicated in controllers" \
  --type decision --scope global

# Sync agent files after new decisions
npx @shahmilsaari/memory-core sync

# Search before making an architectural decision
npx @shahmilsaari/memory-core search "caching strategy"

# Try to commit code that breaks rules → hook blocks it with explanation
git commit -m "add user endpoint"

Environment variables

Troubleshooting

extension "vector" is not available pgvector not installed for your PostgreSQL version. See pgvector setup.

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.

DATABASE_URL is not set Create .env in your project root. See Configure environment.

createdb: role does not exist

createuser -s $(whoami)

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.

Roadmap

License

MIT