memory-core

Every AI coding agent in your project, following your rules. Automatically.

You decide the architecture. memory-core remembers it. Every AI tool — Copilot, Cursor, Claude Code, Windsurf, and 10 more — reads those rules before writing a single line of code.

npx @shahmilsaari/memory-core init

No OpenAI key. No cloud. Fully local.

What does it actually do?

Without memory-core, every AI agent starts fresh. It doesn't know you're using Clean Architecture. It doesn't know controllers shouldn't call the database. It doesn't know why you made that decision six months ago.

With memory-core:

1. You run init once and answer a few questions about your project
2. memory-core generates config files for every AI agent you use
3. Those agents read the files and follow your rules — automatically
4. When you commit code, a hook catches violations before they land in the repo
5. Watch mode catches violations as you type, not just at commit time

Before you start

You need three things installed:

Install

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

pgvector

pgvector adds AI-powered search to PostgreSQL.

macOS + PostgreSQL 17+ (easiest)

brew install pgvector

macOS + PostgreSQL 16 (brew's pgvector targets 17+, so 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

Linux

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

Check it worked:

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

Ollama

Ollama runs AI models on your machine. Two models are needed — one for search, one for code checking.

macOS

brew install ollama
brew services start ollama

Linux

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

Windows — download from ollama.com

Then pull the two models:

ollama pull nomic-embed-text   # used for search
ollama pull llama3.2           # used to check your code

Create the database

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

setup.sql:

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

Quick start

# 1. Go to your project
cd my-api

# 2. Initialize — answers a few questions, generates all config files
npx @shahmilsaari/memory-core init

# 3. Load 192 predefined best-practice rules
npx @shahmilsaari/memory-core seed

# 4. Install the pre-commit hook (optional but recommended)
npx @shahmilsaari/memory-core hook install

That's it. Every AI agent in your project now has your rules.

Commands

init — Set up a project

npx @shahmilsaari/memory-core init

Asks you:

• Project name
• Project type (Backend / Frontend / Fullstack)
• Architecture (Clean Architecture, MVC, React, Vue, etc.)
• Language
• Whether to enable caveman mode (optional token saver)

Generates config files for every supported AI agent and saves your choices to .memory-core.json.

remember — Save a decision

Made a decision your team should never forget? Save it.

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

It will ask you why — that reason gets stored alongside the rule and shown to AI agents and developers when a violation is caught.

With flags (skip the prompts):

npx @shahmilsaari/memory-core remember "Use DTOs for all API responses" \
  --type rule \
  --scope global \
  --reason "Raw DB entities expose internal schema and sensitive fields" \
  --tags "api,dto"

sync — Refresh all agent files

After saving new memories, regenerate every agent file to include them.

npx @shahmilsaari/memory-core sync

search — Find a rule or decision

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

Uses AI search — finds related rules even if you don't use the exact words.

seed — Load predefined rules

192 best-practice rules across all supported architectures, each with a plain-English reason explaining why the rule exists.

npx @shahmilsaari/memory-core seed                              # all architectures
npx @shahmilsaari/memory-core seed --arch clean-architecture   # one only
npx @shahmilsaari/memory-core seed --force                     # re-seed existing

hook install — Block bad commits

npx @shahmilsaari/memory-core hook install

Installs a git pre-commit hook. Every time you run git commit, your staged files are checked against your architecture rules before the commit goes through.

When a violation is found, the commit is blocked and you see exactly what's wrong and how to fix it:

  ✗ 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 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 tie business logic to infrastructure
      Issue:  Imports 'typeorm' directly
      Fix:    Define IUserRepository interface in domain/

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

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

watch — Catch violations as you type

npx @shahmilsaari/memory-core watch

Runs in the background and checks each file the moment you save it. You see violations immediately — before you even think about committing.

  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 other entry points
      Issue:  Password hashing inside the route handler
      Fix:    Move to UserService.hashPassword()

Options:

npx @shahmilsaari/memory-core watch --path src/   # watch a specific folder only
npx @shahmilsaari/memory-core watch --verbose     # show extra details

Only checks source files — ignores node_modules, dist, config files, JSON, etc.

check — Manual check (for CI)

npx @shahmilsaari/memory-core check --staged           # check staged files
npx @shahmilsaari/memory-core check --staged --verbose # with extra detail

Same as the pre-commit hook. Use this in CI/CD pipelines.

global — Apply rules to every project

npx @shahmilsaari/memory-core global

Writes your rules to the global config of each AI agent — so they follow your rules in every project on your machine, not just the current one.

Supported agents

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

Architecture profiles

Pick the one that matches how your project is structured.

Backend

Frontend

Fullstack projects get both sections in every generated file.

Caveman mode (optional)

Cuts AI response length by 65–75% by removing filler words. Opt in during init.

Day-to-day workflow

# Starting a new project
cd my-api
npx @shahmilsaari/memory-core init
npx @shahmilsaari/memory-core seed
npx @shahmilsaari/memory-core hook install

# Made an architectural decision? Save it.
npx @shahmilsaari/memory-core remember "All auth goes through middleware, never in controllers" \
  --type decision --scope global

# Refresh agent files after saving new memories
npx @shahmilsaari/memory-core sync

# Not sure how something was decided? Search.
npx @shahmilsaari/memory-core search "caching strategy"

# Commit code → hook checks it automatically
git commit -m "add user endpoint"

Environment variables

memory-core creates .memory-core.env automatically during init. You can also set these manually:

Troubleshooting

extension "vector" is not available pgvector isn't installed for your PostgreSQL version. Follow the pgvector install steps above.

Ollama not running — skipping rule check Start Ollama: brew services start ollama (macOS) or ollama serve (Linux).

Chat model "llama3.2" not found Run ollama pull llama3.2. Or switch to another model: add OLLAMA_CHAT_MODEL=mistral to .memory-core.env.

DATABASE_URL is not set Run npx @shahmilsaari/memory-core init — it will create the .memory-core.env file for you.

createdb: role does not exist

createuser -s $(whoami)

Hook is flagging JSON or config files It won't — the hook only checks source code files: .ts .tsx .js .jsx .py .php .rb .go .java .cs .swift .kt .rs .vue .svelte. Everything else is skipped automatically.

Roadmap

License

MIT