amem: Instructions file for GitHub Copilot

Copilot Instructions for amem

Build, Test, Lint

npm run build                                # tsc — must produce zero errors
npm test                                     # vitest run — full suite
npx vitest run tests/memory.test.ts          # single test file
npx vitest run -t "should compute score"     # single test by name
npm run dev                                  # tsc --watch

No linter is configured. The TypeScript compiler (strict: true) is the primary safety net.

Architecture

amem is an MCP server that gives AI coding tools persistent, searchable memory backed by SQLite. It communicates over stdio and exposes 23 tools, 6 resources, and 2 prompts via the MCP protocol.

Module dependency chain

index.ts  — entry point: MCP server init, project detection, resource/prompt registration, auto-backup
  ├── database.ts  — SQLite layer: 7 tables, prepared statements, FTS5 triggers, migrations
  │     └── transaction(), resolveId(), resolveReminderId(), getAllRelations() — centralized DB ops
  ├── tools/       — 23 MCP tool registrations, split by domain:
  │     ├── index.ts      — registerTools() orchestrator + re-exports (TYPE_ORDER, formatAge)
  │     ├── helpers.ts    — shared constants (SHORT_ID_LENGTH, CHARACTER_LIMIT) and utilities
  │     ├── memory.ts     — 12 core tools: store, recall, detail, context, forget, extract, stats, export, inject, consolidate, patch, import
  │     ├── versions.ts   — memory_versions tool
  │     ├── log.ts        — memory_log, memory_log_recall, memory_log_cleanup tools
  │     ├── graph.ts      — memory_relate, memory_since, memory_search tools
  │     └── reminders.ts  — reminder_set, reminder_list, reminder_check, reminder_complete tools
  ├── memory.ts    — ranking engine (scoring, consolidation, recall, explain mode)
  ├── schemas.ts   — Zod output schemas (discriminated unions)
  ├── embeddings.ts — HuggingFace all-MiniLM-L6-v2 (optional, graceful fallback)
  └── cli.ts  — standalone CLI entry point (read-only DB operations)