code-memory

A CLI tool that generates intelligent project memory for AI coding assistants. Instead of letting the AI scan your entire codebase every session, code-memory creates compact summaries with exports, types, dependencies, and a full dependency graph — reducing token usage by up to 93%.

The Problem

Every time an AI assistant starts a new session on your project, it needs to understand the codebase from scratch. For a project with 162 files (~200k tokens), the AI wastes thousands of tokens just reading files to build context.

The Solution

code-memory scan

✔ 162 files scanned
✔ 16 modules analyzed (exports, imports, types)
✔ memory saved to .ai-memory/
✔ summaries updated

📊 Real impact:
   Source code:  202.2k tokens (789.8 KB)
   .ai-memory/:  15.5k tokens (60.5 KB)
   Savings:      92% fewer tokens per session

One command generates a .ai-memory/ directory with everything the AI needs — module summaries, full export signatures, and a dependency graph. The AI reads 15k tokens instead of 200k and understands your project immediately.

Features

• Deep analysis — Extracts exported functions, classes, interfaces, types, and enums with full signatures using ts-morph
• Dependency graph — Maps internal dependencies between modules with impact analysis (which modules break if you change this one?)
• Monorepo support — Automatically detects apps/, packages/ structures and groups intelligently
• File watcher — Watches for changes and updates only the affected module in real-time
• CLAUDE.md integration — Automatically configures Claude Code to read .ai-memory/ before starting any task
• Real token measurement — Measures actual bytes instead of estimates

Install

git clone https://github.com/YOUR_USERNAME/code-memory.git
cd code-memory
npm install
npm link

Now code-memory is available globally.

Usage

Scan a project

# Scan current directory
code-memory scan

# Scan a specific project
code-memory scan /path/to/project

Watch for changes

code-memory watch

Runs an initial scan, then watches for file changes and updates only the affected module.

What it generates

.ai-memory/
  dependency-graph.md    # Full dependency graph with impact analysis
  project-map.json       # Complete file map
  apps/
    api/
      modules.md         # Module summary with exports and deps
      common.md
      prisma.md
    dashboard/
      components.md
      hooks.md
      store.md
  packages/
    types.md
    utils.md

Module summary example

# Apps/api/modules Module

## Files (38)
- apps/api/src/modules/auth/auth.controller.ts
- apps/api/src/modules/auth/auth.service.ts
...

## Exports

### Classes
- `class AuthService { register(dto: RegisterDto); login(email, password, tenantId); refresh(refreshToken); forgotPassword(email) }`
- `class PropertyService { findAll(tenantId); create(tenantId, data); update(tenantId, id, data); remove(tenantId, id) }`

## Internal dependencies
- → apps/api/common
- → apps/api/prisma

## External dependencies
`@nestjs/common`, `stripe`, `@aws-sdk/client-s3`, `bcryptjs`

Dependency graph example

# Dependency Graph

## Module → Depends on
- **apps/api/modules** → apps/api/prisma, apps/api/common
- **apps/dashboard/pages** → apps/dashboard/components, apps/dashboard/store

## Module ← Used by
- **apps/api/prisma** ← apps/api, apps/api/common, apps/api/modules

## Impact analysis

Modules ordered by number of dependents (highest impact first):

🔴 **apps/api/prisma** — 3 dependents (apps/api, apps/api/common, apps/api/modules)
🟡 **apps/dashboard/components** — 2 dependents (apps/dashboard/layouts, apps/dashboard/pages)
🟢 **apps/dashboard/pages** — 1 dependent (apps/dashboard)

## Isolated modules

No internal dependencies (can be changed without impact):

- packages/types
- packages/utils

Architecture

src/
  cli.ts              # CLI entry point
  scanner/index.ts     # File discovery with fast-glob
  analyzer/index.ts    # Deep analysis with ts-morph (exports, imports, types)
  memory/index.ts      # Memory generation (summaries, graph, token measurement)
  watcher/index.ts     # Real-time file watching with chokidar

How it works

1. Scanner — Finds all .ts, .tsx, .js, .jsx files (ignoring node_modules, dist, etc.)
2. Analyzer — Uses ts-morph to parse each file and extract exported functions, classes, interfaces, types, enums, and import relationships
3. Memory — Groups files by module, generates markdown summaries with full export signatures, builds the dependency graph with impact analysis
4. CLAUDE.md — Injects instructions so Claude Code reads .ai-memory/ automatically on every session

Tech stack

• TypeScript + tsx — Zero-config TS execution
• ts-morph — TypeScript AST analysis for extracting exports and imports
• fast-glob — Fast file discovery
• chokidar — File system watcher

License

MIT