memories-dev

Name: memories-dev
Rating: 92
Author: WebRenew

Developer guide for contributing to the memories.sh monorepo.

Project Structure

code

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

code

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

File	Purpose
`db.ts`	SQLite via libSQL. Schema migrations, FTS5 triggers, `getDb()` singleton
`memory.ts`	All memory operations: add, search, list, forget, update, getContext, getRules, streaming
`embeddings.ts`	Local embeddings via Xenova/Transformers. `generateEmbedding()`, cosine similarity
`git.ts`	`getProjectId()` — derives project ID from git remote URL
`auth.ts`	Cloud auth token storage, device code flow helpers
`turso.ts`	Turso embedded replica sync (cloud ↔ local)
`config.ts`	YAML config read/write (`~/.config/memories/`)
`setup.ts`	Tool detection (Cursor, Claude, Windsurf, VS Code), MCP config setup
`templates.ts`	Built-in memory templates (decision, error-fix, api-endpoint, etc.)
`ui.ts`	Terminal styling: chalk, figlet, gradient, boxen

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

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

typescript

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
  });

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

typescript

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

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

Adding a New MCP Tool

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

typescript

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

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

Build & Test

bash

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

Layer	Technology
CLI framework	Commander.js
Database	libSQL (SQLite-compatible)
Full-text search	FTS5
Embeddings	Xenova/Transformers (local)
MCP SDK	@modelcontextprotocol/sdk
Build	tsup (CLI), Next.js (web)
Web framework	Next.js 15 (App Router)
Auth	Supabase Auth
Cloud sync	Turso embedded replicas
Payments	Stripe
Docs	Fumadocs
UI	shadcn/ui, Tailwind CSS v4
Testing	Vitest

Reference Files

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