memories-dev

Developer guide for contributing to the memories.sh monorepo.

Project Structure

memories/
├── packages/
│   ├── cli/                  # @memories.sh/cli (npm package)
│   │   ├── src/
│   │   │   ├── commands/     # CLI commands (Commander.js)
│   │   │   ├── lib/          # Core: db, memory, auth, embeddings, git
│   │   │   └── mcp/          # MCP server (stdio + HTTP)
│   │   ├── tsup.config.ts    # Build config
│   │   └── package.json
│   └── web/                  # Next.js marketing + dashboard
│       ├── src/app/          # App Router pages + API routes
│       ├── src/components/   # UI components (shadcn/ui)
│       ├── src/lib/          # Auth, Stripe, Supabase, Turso
│       └── content/docs/     # Fumadocs documentation
├── supabase/                 # Database migrations
├── skills/                   # Distributable skills (this directory)
└── pnpm-workspace.yaml

Architecture Overview

Dependency Graph

db.ts (SQLite/libSQL, migrations, FTS5)
  ↓
memory.ts (CRUD, search, context, streaming)
  ↑          ↑
git.ts    embeddings.ts (Xenova/Transformers, cosine similarity)
  ↓
Commands ← auth.ts, turso.ts, config.ts, setup.ts
  ↓
MCP Server (stdio + StreamableHTTP transports)

Key Lib Files

Database Schema

SQLite with FTS5 full-text search:

• memories — Main table: id, content, type, tags, scope, project_id, created_at, updated_at, deleted_at
• memories_fts — FTS5 virtual table, synced via triggers
• memory_embeddings — Vector storage: memory_id, embedding (JSON float array), model
• memory_links — Bidirectional links: id1, id2, link_type
• memory_history — Version tracking: memory_id, version, content, tags, change_type

Adding a New CLI Command

1. Create packages/cli/src/commands/mycommand.ts:

import { Command } from "commander";

export const myCommand = new Command("mycommand")
  .description("What it does")
  .argument("<required>", "Description")
  .option("-f, --flag <value>", "Description", "default")
  .action(async (required, opts) => {
    // Use lib functions from ../lib/
    // Use ui.ts for styled output
  });

2. Register in packages/cli/src/index.ts:

import { myCommand } from "./commands/mycommand.js";
program.addCommand(myCommand);

3. Add tests in packages/cli/src/commands/mycommand.test.ts.

Adding a New MCP Tool

Edit packages/cli/src/mcp/index.ts:

server.tool(
  "tool_name",
  "Description of what the tool does",
  {
    param: z.string().describe("Parameter description"),
  },
  async ({ param }) => {
    // Implementation
    return {
      content: [{ type: "text", text: "Result" }],
    };
  }
);

Parameters use Zod schemas. Return { isError: true } for errors.

Adding a New Generation Target

1. Add template to packages/cli/src/lib/templates.ts
2. Register in the generation targets map
3. Add detection in packages/cli/src/lib/setup.ts
4. Add docs page in packages/web/content/docs/integrations/

Build & Test

pnpm build          # Build all packages
pnpm typecheck      # TypeScript checks
pnpm test           # Run all tests (vitest)

# CLI-specific
cd packages/cli
pnpm dev            # Watch mode (tsup)
pnpm test           # CLI tests only

# Web-specific
cd packages/web
pnpm dev            # Next.js dev server
pnpm build          # Production build

Tech Stack

Reference Files

• Architecture deep-dive: See references/architecture.md for detailed module descriptions and data flow