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

Fully local or cloud — your choice. v0.2.10

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 — it verifies your PostgreSQL and Ollama connections, picks your model, lets you choose which agents to generate files for, and installs a pre-commit hook
2. Those agents read the files and follow your rules — automatically
3. Watch mode catches violations as you type, not just at commit time
4. When you commit, the hook checks your code before the commit goes through (advisory by default — logs violations but never blocks)

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

Pull the embedding model. The code-checking model is chosen during init:

ollama pull nomic-embed-text   # required for search
ollama pull llama3.2           # or whichever model you plan to use

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 — verifies connections, picks your model, generates config files
npx @shahmilsaari/memory-core init

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

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

Commands

init — Set up a project

npx @shahmilsaari/memory-core init

Walks you through:

• PostgreSQL connection URL — tested live, retries until connected
• Ollama URL — tested live, retries until reachable (used for embeddings)
• Code-checking provider — Ollama (local), OpenAI, Anthropic, or MiniMax
• Code-checking model — picked from a list, verified before continuing
• Project name, type, architecture, language
• Which agents to generate files for — multi-select, all pre-checked, Space to deselect — saved to .memory-core.json
• Hook mode — advisory (logs violations, never blocks) or strict (blocks commits)
• Whether to enable caveman mode (optional token saver)

Generates config files for every selected AI agent, saves your choices to .memory-core.json, and automatically adds all generated files to .gitignore under a # memory-core generated files block.

At the end, the banner shows live ✓/✗ status for PostgreSQL and Ollama so you know everything is working.

sync — Refresh all agent files

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

npx @shahmilsaari/memory-core sync

Multi-selects which agents to sync (pre-checked from your .memory-core.json config). Skips files that haven't changed and reports how many were updated vs already up to date:

  3 updated, 11 already up to date

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"

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

281 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

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.

hook install — Install the pre-commit hook

npx @shahmilsaari/memory-core hook install             # advisory mode (default)
npx @shahmilsaari/memory-core hook install --advisory  # logs violations, never blocks
npx @shahmilsaari/memory-core hook install --strict    # blocks commits on violations

Installs a git pre-commit hook in the current project. Every time you run git commit, your code is checked against your architecture rules.

Advisory mode (default): violations are logged so you can see them, but the commit always goes through. Useful for getting used to the rules without disrupting your flow.

Strict mode: violations block the commit entirely. 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>"

The hook mode is chosen during init — no separate step needed unless you want to change it later.

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

list — List memories from the database

npx @shahmilsaari/memory-core list

Shows all stored memories. Filter the results:

npx @shahmilsaari/memory-core list --type rule
npx @shahmilsaari/memory-core list --scope global
npx @shahmilsaari/memory-core list --arch clean-architecture
npx @shahmilsaari/memory-core list --limit 50

remove — Delete a memory

npx @shahmilsaari/memory-core remove <id>

Deletes a memory by its ID. Get the ID from list or search.

edit — Edit a memory

npx @shahmilsaari/memory-core edit <id>

Opens the memory interactively so you can update its content, reason, tags, type, or scope.

export — Export memories to a file

npx @shahmilsaari/memory-core export
npx @shahmilsaari/memory-core export --output path/to/my-rules.json

Exports all memories from the database to memories.json in the project root (or the path you specify). Makes your rules portable and version-controllable — commit the file alongside your code.

import — Import memories from a file

npx @shahmilsaari/memory-core import
npx @shahmilsaari/memory-core import --file path/to/my-rules.json
npx @shahmilsaari/memory-core import --url https://example.com/team-rules.json

Imports memories into the local database. Skips duplicates by content hash — safe to run more than once.

ignore — Mark false positives

npx @shahmilsaari/memory-core ignore "controllers may import prisma directly in migration scripts"

Saves a pattern so the hook and watcher never flag it again. Useful for intentional exceptions to a rule.

npx @shahmilsaari/memory-core ignore --list          # show all saved ignore patterns
npx @shahmilsaari/memory-core ignore --remove <id>   # delete an ignore pattern

ci-setup — GitHub Actions integration

npx @shahmilsaari/memory-core ci-setup

Generates .github/workflows/memory-core.yml. Adds a PR check that runs your architecture rules on every pull request — same checks as the local hook, enforced in CI.

stats — Violation counters

npx @shahmilsaari/memory-core stats

Shows which rules fire most often and which files have the most violations. Useful for spotting systemic issues in the codebase.

reset — Remove all generated files

npx @shahmilsaari/memory-core reset              # remove all generated files + .memory-core.json
npx @shahmilsaari/memory-core reset --soft       # keep config and DB, remove only generated files
npx @shahmilsaari/memory-core reset --db         # also drop the memories table from the database

Cleans up everything memory-core created. Use --soft if you want to re-run init without losing your saved memories.

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   # verifies connections, picks model, selects agents, installs hook
npx @shahmilsaari/memory-core seed   # load 281 best-practice rules

# 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"

# See what rules are saved
npx @shahmilsaari/memory-core list --type rule

# Export rules to version control
npx @shahmilsaari/memory-core export

# Commit code → hook checks it automatically before committing
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 provider/model by updating CHAT_PROVIDER and CHAT_MODEL in .memory-core.env.

Using an API key instead of Ollama for code checking During init choose OpenAI, Anthropic, or MiniMax when prompted for the check provider. Or set manually in .memory-core.env:

CHAT_PROVIDER=openai
CHAT_MODEL=gpt-4o
CHAT_API_KEY=sk-...

Embeddings always use Ollama (nomic-embed-text) regardless of provider.

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.

Hook is flagging something that's intentional Save an ignore pattern: npx @shahmilsaari/memory-core ignore "your exception here". The hook and watcher will never flag it again.

Roadmap

License

MIT

Built by Shahmil Saari