Tages — Project Configuration

Overview

Tages is an open-source MCP server + CLI + dashboard that gives AI coding agents persistent, cross-session memory about codebases. Named after the Etruscan divine child who dictated sacred knowledge to scribes.

Repo: https://github.com/ryantlee25-droid/tages Stack: pnpm monorepo — Node.js/TypeScript npm packages: @tages/cli (CLI), @tages/server (MCP server), @tages/shared (types)

Architecture

packages/
  server/     # MCP server (@modelcontextprotocol/sdk, stdio transport)
              # 56 MCP tools, 22 server modules, 74 test suites (817 tests: 804 passing, 13 skipped)
  cli/        # tages CLI (commander.js, 42 top-level commands, 71 incl. subcommands)
  shared/     # Shared types + Supabase client factory
apps/
  dashboard/  # Next.js 16 + Supabase Auth + Tailwind + shadcn/ui
              # Auth, project list, memory browser, stats, conflicts, graph
supabase/
  migrations/ # 64 Postgres migrations (schema, RLS, RPCs, indexes)

Key Design Decisions

• Primary storage: Supabase Postgres with pg_trgm fuzzy search + pgvector semantic search
• Local cache: SQLite (better-sqlite3) for sub-10ms MCP queries, 60s async sync to Supabase
• Auth: Supabase Auth with GitHub OAuth; CLI tokens hashed with SHA-256
• Encryption: Optional AES-256-GCM field-level encryption (set TAGES_ENCRYPTION_KEY)
• LLM for auto-indexing: Ollama (local) -> Claude Haiku (API) -> dumb mode (file paths only)
• Transport: stdio (standard for Claude Code / Cursor MCP integration)

Security

• RBAC: Owner/admin can write, member read-only (migration 0031)
• RLS: Enabled on all tables with per-user/per-project policies
• Token management: SHA-256 hashed, supports expiration + tages token rotate
• Encryption at rest: AES-256-GCM for memory values (opt-in via env var)
• Secret/PII detection: Blocks high-severity secrets, warns on PII before storage
• Auth audit logging: Tracks login success/failure, token validation events
• Transport security: HSTS, CSP (no unsafe-eval in production), SameSite=Strict cookies
• Input validation: Zod schemas on all 56 MCP tools, URL slug validation, 1MB request limits
• SECURITY.md: Responsible disclosure policy at repo root

Commands

pnpm install          # install all workspace deps
pnpm build            # build all packages (server + cli + dashboard)
pnpm dev              # start dashboard dev server (localhost:3000)
pnpm test             # run all tests (1,228 vitest tests passing across all packages)
pnpm typecheck        # tsc --noEmit across all packages
pnpm --filter server test  # server tests only

CLI (@tages/cli)

Core: init, remember, recall, forget, status, dashboard Advanced: dedup, impact, risk, enforce, quality, templates, archive, federation Auth: token rotate [--expires-in <days>]

Memory Staging

When working on this repo, use the staging workflow to avoid noisy live-memory pollution:

• Use observe for passive capture — conventions you notice, decisions inferred, lessons from failures. These land in the pending queue, not live memory.
• Use remember only for verified, user-confirmed facts.
• At the end of a work session, run tages pending to review staged memories.
• Bulk-approve high-confidence entries: tages pending --approve-all --min-confidence 0.8
• To opt into auto-promotion for this project: tages settings auto-save 0.85 (memories with confidence >= 0.85 are promoted to live automatically)
• Never call session_end unless the user explicitly requests it.

Conventions

• TypeScript strict mode everywhere
• Shared types in packages/shared/src/types.ts — import as @tages/shared
• Supabase client via createSupabaseClient() from @tages/shared
• MCP tools use Zod for input validation (packages/server/src/schemas.ts)
• Tests with vitest (packages/server/vitest.config.ts excludes dist/)
• CLI output uses chalk for color, ora for spinners
• Supabase .from().insert() returns PromiseLike not Promise — wrap with Promise.resolve() for .catch()
• Cross-package CLI imports use @ts-ignore with expanded rootDir (../../)
• Migrations use sequential numbers (0001-0064, one archived), cast TEXT params to ::uuid for uuid columns