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.16

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,
  context      JSONB NOT NULL DEFAULT '{}',
  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

For the full CLI reference, examples, and command behavior notes, see COMMANDS.md.

New setup-management commands:

• memory-core status — show project name, provider/model, agents, hook state, generated files, and health checks
• memory-core auto-sync — show or change automatic agent file regeneration (on, off, or status)
• memory-core provider set <provider> — switch code-checking provider without rerunning init
• memory-core model set <model> — update chat or embedding model from the CLI
• memory-core model doctor — verify database, Ollama, model installation, and cloud API key presence

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, enables auto-sync by default, 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

Regenerate every agent file on demand. This still exists even though remember, import, edit, remove, forget, and ignore auto-sync by default after changing memories.

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

Use --no-sync on memory-changing commands when you want to save database changes without regenerating files immediately.

Manage the default:

npx @shahmilsaari/memory-core auto-sync        # show current setting
npx @shahmilsaari/memory-core auto-sync off    # save only, sync manually later
npx @shahmilsaari/memory-core auto-sync on     # restore default behavior

Auto-sync failures are non-fatal. If regeneration cannot run, memory-core prints the reason and tells you to run memory-core sync manually.

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" \
  --applies-to "controllers,API responses" \
  --avoid-when "internal domain transformations" \
  --example "return UserResponseDto instead of UserEntity" \
  --tags "api,dto"

Structured context is stored in the database as JSON and rendered into generated agent files as Why, Use when, Avoid when, and Examples, which gives AI agents clearer guidance than a flat rule sentence.

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
npx @shahmilsaari/memory-core watch --debug       # show prompt, diff, and raw model output

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
npx @shahmilsaari/memory-core check --staged --debug   # show prompt, diff, and raw model output
npx @shahmilsaari/memory-core check --ci               # CI mode using memories.json

--staged is the same path used by the pre-commit hook. --ci reads memories.json and uses a deterministic CI-friendly diff check, so pull requests can enforce rules without a local database or Ollama setup.

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

By default, shows memories relevant to the current project context: detected stack, current project name, plus shared/global memories. Use --all for the old database-wide view.

npx @shahmilsaari/memory-core list --all
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 --project my-api
npx @shahmilsaari/memory-core list --limit 50

remove — Delete a memory

npx @shahmilsaari/memory-core remove <id>
npx @shahmilsaari/memory-core remove <id> --no-sync

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

forget — Bulk-delete memories

npx @shahmilsaari/memory-core forget --tag nextjs --scope global
npx @shahmilsaari/memory-core forget --type ignore
npx @shahmilsaari/memory-core forget --arch nuxt

Deletes memories by filter. At least one filter is required, so an empty forget command cannot wipe the database by accident.

edit — Edit a memory

npx @shahmilsaari/memory-core edit <id>
npx @shahmilsaari/memory-core edit <id> --no-sync

Opens the memory interactively so you can update its content, reason, structured context, 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
npx @shahmilsaari/memory-core import --no-sync

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
npx @shahmilsaari/memory-core ignore "..." --no-sync # save without regenerating agent files

allow — Allow intentional project patterns

npx @shahmilsaari/memory-core allow "generated by sqlc"
npx @shahmilsaari/memory-core allow --list
npx @shahmilsaari/memory-core allow --remove "generated by sqlc"

Stores lightweight per-project allowlist strings in .memory-core.json. Hook and watch checks treat these patterns as intentional before surfacing violations.

ci-setup — GitHub Actions integration

npx @shahmilsaari/memory-core ci-setup

Generates .github/workflows/memory-core.yml. Adds a PR check that runs npx @shahmilsaari/memory-core check --ci, using memories.json so CI can enforce architecture rules without a project-local database.

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

# Optional: refresh agent files manually anytime
npx @shahmilsaari/memory-core sync

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

# Inspect current setup, provider, model, and health checks
npx @shahmilsaari/memory-core status

# Switch code-checking provider or model without rerunning init
npx @shahmilsaari/memory-core provider set openai --model gpt-4o-mini --api-key $OPENAI_API_KEY
npx @shahmilsaari/memory-core model set qwen2.5-coder --provider ollama

# 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 with npx @shahmilsaari/memory-core provider set ... or npx @shahmilsaari/memory-core model set ....

Using an API key instead of Ollama for code checking During init choose OpenAI, Anthropic, or MiniMax when prompted for the check provider. Or switch later:

npx @shahmilsaari/memory-core provider set openai --model gpt-4o --api-key sk-...

Equivalent manual .memory-core.env settings:

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.

Not sure what memory-core is configured to use Run npx @shahmilsaari/memory-core status.

Need to verify the model/database setup Run npx @shahmilsaari/memory-core model doctor.

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.

Release checks

Before publishing, run the same checks as CI:

npm run lint
npm run typecheck
npm test
npm run build
npm run smoke:pack
npm run smoke:npx

smoke:pack verifies the npm tarball includes the built CLI plus templates/profiles. smoke:npx installs that tarball into a fresh temporary project and runs npx --no-install memory-core init --quick.

Roadmap

License

MIT

Built by Shahmil Saari