What is DevMem?

$ devmem init

  Crawling codebase...           done  (312 files, 0.1s)
  Detecting modules...           found 7 candidates

  Detected modules:
    auth       src/auth/         (score: 7)
    api        src/api/          (score: 6)
    db         internal/db/      (score: 5)
    worker     internal/worker/  (score: 4)
    config     pkg/config/       (score: 3)

  Confirm? [Y/n]: Y

  Analysing modules (7 total, max 5 parallel)...
    [1/7] auth      ✓ done  (1.2s)
    [3/7] api       ✓ done  (1.4s)
    [2/7] db        ✓ done  (1.8s)
    [5/7] config    ✓ done  (0.9s)
    [4/7] worker    ✓ done  (2.1s)

  Generating master architecture...  ✓ done  (2.3s)

  devmem initialised. 7 modules documented.

.devmem/
├── config.json                      Module map, ignore rules, model config
├── state.json                       Init timestamp, last commit hash, module count
├── tree.json                        Complete FileNode snapshot
└── docs/
    ├── master-architecture.md       Full system overview with module table
    ├── master-architecture.mermaid  Mermaid graph of module dependencies
    └── modules/
        ├── auth.md
        ├── api.md
        └── ...

# Install the hook
devmem init   # hook is offered during init

# Or install manually
devmem capture --install-hook

#!/bin/sh
# Installed by devmem
devmem capture

devmem status

  Last captured commit: abc123f  (2 commits behind)
  Current commit:       def789g

  Modules with undocumented changes:
    api        src/api/handler.go, src/api/routes.go
    worker     internal/worker/processor.go

  Run: devmem capture  to update docs

- name: Check documentation is current
  run: devmem status

devmem query "<question>"

$ devmem query "how does authentication work?"
$ devmem query "which modules depend on the database layer?"
$ devmem query "what changed in the auth module recently?"
$ devmem query "explain the overall architecture in plain English"

type FileNode struct {
    Name     string      `json:"name"`
    Path     string      `json:"path"`      // relative to repo root
    Type     string      `json:"type"`      // "file" | "dir"
    Ext      string      `json:"ext,omitempty"`
    Size     int64       `json:"size,omitempty"`
    Children []*FileNode `json:"children,omitempty"`
}

.git
.devmem
node_modules
vendor
.venv
__pycache__
dist
build
*.lock
*.sum
*.min.js

- First character must be {
- Last character must be }
- Return exactly one JSON object
- Do not include markdown code fences
- Fill all required fields even if value is an empty list

results := make(chan analysisResult, len(modules))
sem := make(chan struct{}, cfg.MaxConcurrent)
var wg sync.WaitGroup

for _, mod := range modules {
    wg.Add(1)
    go func(m crawler.Module) {
        defer wg.Done()
        sem <- struct{}{}
        defer func() { <-sem }()

        analysis, err := aiClient.AnalyseModule(ctx, buildContext(tree, m))
        results <- analysisResult{module: m, analysis: analysis, err: err}
    }(mod)
}

go func() {
    wg.Wait()
    close(results)
}()

for r := range results {
    // write docs as each result arrives
}

.devmem/
├── config.json              Configuration, module map, ignore rules
├── state.json               Runtime state, last commit, module count
├── tree.json                FileNode snapshot from last init
├── docs/
│   ├── master-architecture.md       System overview document
│   ├── master-architecture.mermaid  Module dependency graph
│   └── modules/
│       ├── auth.md                  Per-module documentation
│       ├── api.md
│       └── ...
└── changelog/
    ├── abc123f4d.md                 One entry per captured commit
    ├── def456g7h.md
    └── ...

---
module: auth
root_path: src/auth
key_files:
  - src/auth/handler.go
  - src/auth/tokens.go
  - src/auth/middleware.go
depends_on:
  - db
  - config
changed_in:
  - abc123f4d
  - def456g7h
generated_at: 2025-03-21T14:32:00Z
---

# auth

JWT-based authentication module handling token issuance,
validation, and HTTP middleware for protected routes.

## Purpose

Provides stateless auth for all API endpoints using RS256-signed JWTs.

## Key files

- `src/auth/handler.go` - login/logout/refresh HTTP handlers
- `src/auth/tokens.go` - token generation, validation, expiry logic
- `src/auth/middleware.go` - Gin middleware, injects claims into context

## Public API

- `NewMiddleware(cfg Config) gin.HandlerFunc`
- `IssueToken(userID string, claims Claims) (string, error)`
- `ValidateToken(raw string) (*Claims, error)`

## Dependencies

- **db** - loads user records for credential validation
- **config** - reads JWT secret and expiry settings

## Tech notes

Uses golang-jwt/jwt v5. Tokens are RS256 signed.
Refresh tokens stored as opaque strings via the cache module.

## Changelog

- [abc123f4d](../changelog/abc123f4d.md) - Added token revocation
- [def456g7h](../changelog/def456g7h.md) - Fixed expiry edge case

---
commit: abc123f4d
type: feature
captured_at: 2026-03-22T09:14:22Z
modules:
  - auth
  - api
---

# Capture abc123f4d

## Summary
Added token revocation endpoint and middleware checks for revoked JWT IDs.

## Module updates
- auth: Added revocation store lookup before token acceptance.
- api: Added route wiring for revoke endpoint.

## Diff context
- src/auth/tokens.go
- src/auth/middleware.go
- src/api/routes.go

{
  "version": "1",
  "ai_model": "claude-sonnet-4-20250514",
  "max_concurrent": 5,
  "ignore": [
    "node_modules",
    "vendor",
    "*.test.go"
  ],
  "modules": {
    "auth": {
      "paths": ["src/auth"]
    },
    "api": {
      "paths": ["src/api"]
    }
  }
}

# build outputs
coverage/
artifacts/

# generated mocks
**/mocks/

# large snapshots
**/*.snap

{
  "modules": {
    "platform-api": {
      "paths": ["services/api", "internal/api"]
    },
    "platform-worker": {
      "paths": ["services/worker"]
    }
  }
}

#!/bin/sh
# Installed by devmem
devmem capture

collect committed diff + worktree diff
-> map files to modules
-> classify change
-> patch modules
-> write changelog
-> update state.json
-> regenerate master architecture only if structural