feat: add entity versioning system with critical bug fixes (v5.3.0)

Entity Versioning (NEW):
- Add complete entity versioning API (brain.versions.*) with 18 methods
- Content-addressable storage with SHA-256 deduplication
- Git-style version control: save, restore, compare, undo, prune
- Auto-versioning augmentation with pattern-based filtering
- Branch-isolated version histories
- Complete integration tests and API documentation

Critical Bug Fixes:
- Fix commit() not updating branch refs (brainy.ts:2385)
  - Root cause: Passed "heads/main" which normalized to "refs/heads/heads/main"
  - Impact: All Git-style versioning features were broken
  - Fix: Pass branch name directly for correct normalization
- Fix VFS entities missing isVFSEntity flag
  - Add isVFSEntity: true to all VFS files/folders for filtering
  - Resolves pollution of semantic search with filesystem entities
  - Updated in writeFile(), mkdir(), and root directory init

Implementation:
- src/versioning/VersionManager.ts - Core versioning engine
- src/versioning/VersionStorage.ts - Content-addressable storage
- src/versioning/VersionIndex.ts - Metadata indexing
- src/versioning/VersionDiff.ts - Version comparison
- src/versioning/VersioningAPI.ts - Public API interface
- src/augmentations/versioningAugmentation.ts - Auto-versioning
- tests/integration/versioning.test.ts - Full integration tests
- tests/unit/versioning/ - Unit test suite

Documentation:
- Complete Entity Versioning API section in docs/api/README.md
- VFS entity filtering guide with examples
- Updated "What's New" section for v5.3.0
- Strategy docs for both critical bugs

Test Results:
- 1168 tests passing
- Build: PASSING (no TypeScript errors)
- Integration tests: ALL PASSING

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/api/README.md

@@ -1,9 +1,9 @@
 # 🧠 Brainy v5.0+ API Reference
 
 > **Complete API documentation for Brainy v5.0+**
-> Zero Configuration • Triple Intelligence • Git-Style Branching
+> Zero Configuration • Triple Intelligence • Git-Style Branching • Entity Versioning
 
-**Updated:** 2025-11-02 for v5.1.0
+**Updated:** 2025-11-04 for v5.3.0
 **All APIs verified against actual code**
 
 ---
@@ -34,6 +34,11 @@ const results = await brain.find({
 const experiment = await brain.fork('test-feature')
 await experiment.add({ data: 'test', type: NounType.Content })
 await experiment.commit({ message: 'Add test data' })
+
+// Entity versioning (v5.3.0+)
+await brain.versions.save(id, { tag: 'v1.0', description: 'Initial version' })
+await brain.update(id, { category: 'AI' })
+await brain.versions.save(id, { tag: 'v2.0' })
 ```
 
 ---
@@ -52,6 +57,9 @@ Vector search + Graph traversal + Metadata filtering in one unified query.
 ### 🌳 Git-Style Branching (v5.0.0+)
 Fork, experiment, commit, and merge - Snowflake-style copy-on-write isolation.
 
+### 📜 Entity Versioning (v5.3.0+)
+Time-travel and history tracking for individual entities - Git-like version control with content-addressable storage.
+
 ---
 
 ## Table of Contents
@@ -61,6 +69,7 @@ Fork, experiment, commit, and merge - Snowflake-style copy-on-write isolation.
 - [Relationships](#relationships)
 - [Batch Operations](#batch-operations)
 - [Branch Management (v5.0+)](#branch-management-v50)
+- [Entity Versioning (v5.3.0+)](#entity-versioning-v530)
 - [Virtual Filesystem (VFS)](#virtual-filesystem-vfs)
 - [Neural API](#neural-api)
 - [Import & Export](#import--export)
@@ -468,10 +477,427 @@ const history = await brain.getHistory({
 
 ---
 
+## Entity Versioning (v5.3.0+)
+
+**NEW in v5.3.0:** Git-style versioning for individual entities with content-addressable storage.
+
+### Overview
+
+Entity Versioning provides time-travel and history tracking for individual entities:
+
+- **Content-Addressable Storage** - Deduplication via SHA-256 hashing
+- **Zero-Config** - Lazy initialization, uses existing indexes
+- **Branch-Isolated** - Versions isolated per branch
+- **Selective Auto-Versioning** - Optional augmentation for automatic version creation
+- **Production-Scale** - Designed for billions of entities
+
+---
+
+### `versions.save(entityId, options?)` → `Promise<EntityVersion>`
+
+Save a new version of an entity.
+
+```typescript
+// Save version with tag
+const version = await brain.versions.save('user-123', {
+  tag: 'v1.0',
+  description: 'Initial user profile',
+  metadata: { author: 'dev@example.com' }
+})
+
+console.log(version.version)      // 1
+console.log(version.contentHash)  // SHA-256 hash
+console.log(version.createdAt)    // Timestamp
+```
+
+**Parameters:**
+- `entityId`: `string` - Entity ID to version
+- `options?`: `object`
+  - `tag?`: `string` - Version tag (e.g., 'v1.0', 'beta')
+  - `description?`: `string` - Version description
+  - `metadata?`: `object` - Additional version metadata
+
+**Returns:** `Promise<EntityVersion>` - Created version
+
+**Features:**
+- Automatic deduplication (identical content = same version)
+- Sequential version numbering (1, 2, 3, ...)
+- Content-addressable storage (SHA-256)
+
+---
+
+### `versions.list(entityId, options?)` → `Promise<EntityVersion[]>`
+
+List all versions of an entity.
+
+```typescript
+const versions = await brain.versions.list('user-123', {
+  limit: 10,
+  offset: 0
+})
+
+versions.forEach(v => {
+  console.log(`Version ${v.version}: ${v.tag} - ${v.description}`)
+})
+```
+
+**Parameters:**
+- `entityId`: `string` - Entity ID
+- `options?`: `object`
+  - `limit?`: `number` - Max versions to return
+  - `offset?`: `number` - Skip versions
+
+**Returns:** `Promise<EntityVersion[]>` - Versions (newest first)
+
+---
+
+### `versions.restore(entityId, versionOrTag)` → `Promise<void>`
+
+Restore entity to a previous version.
+
+```typescript
+// Restore by version number
+await brain.versions.restore('user-123', 1)
+
+// Restore by tag
+await brain.versions.restore('user-123', 'beta')
+```
+
+**Parameters:**
+- `entityId`: `string` - Entity ID
+- `versionOrTag`: `number | string` - Version number or tag
+
+---
+
+### `versions.compare(entityId, version1, version2)` → `Promise<VersionDiff>`
+
+Compare two versions.
+
+```typescript
+const diff = await brain.versions.compare('user-123', 1, 2)
+
+console.log(diff.totalChanges)    // Total changes
+console.log(diff.modified)        // Modified fields
+console.log(diff.added)           // Added fields
+console.log(diff.removed)         // Removed fields
+
+// Check specific changes
+const nameChange = diff.modified.find(c => c.path === 'metadata.name')
+console.log(`${nameChange.oldValue} → ${nameChange.newValue}`)
+```
+
+**Returns:** `Promise<VersionDiff>` - Detailed diff with field-level changes
+
+---
+
+### `versions.getContent(entityId, versionOrTag)` → `Promise<EntitySnapshot>`
+
+Get version content without restoring.
+
+```typescript
+// View old version without changing current state
+const v1Content = await brain.versions.getContent('user-123', 1)
+console.log(v1Content.metadata.name)  // Old name
+
+// Current state unchanged
+const current = await brain.get('user-123')
+console.log(current.metadata.name)  // Current name
+```
+
+---
+
+### `versions.undo(entityId)` → `Promise<void>`
+
+Undo to previous version (shorthand for restore to latest-1).
+
+```typescript
+// Make a bad change
+await brain.update('user-123', { status: 'deleted' })
+
+// Undo immediately
+await brain.versions.undo('user-123')
+```
+
+**Alias:** `versions.revert(entityId)`
+
+---
+
+### `versions.prune(entityId, options)` → `Promise<PruneResult>`
+
+Clean up old versions.
+
+```typescript
+const result = await brain.versions.prune('user-123', {
+  keepRecent: 10,      // Keep 10 most recent
+  keepTagged: true,    // Always keep tagged versions
+  olderThan: Date.now() - 30 * 24 * 60 * 60 * 1000  // Older than 30 days
+})
+
+console.log(`Deleted ${result.deleted}, kept ${result.kept}`)
+```
+
+**Parameters:**
+- `keepRecent?`: `number` - Keep N most recent versions
+- `keepTagged?`: `boolean` - Always keep tagged versions (default: true)
+- `olderThan?`: `number` - Only prune versions older than timestamp
+
+---
+
+### `versions.getLatest(entityId)` → `Promise<EntityVersion | null>`
+
+Get latest version.
+
+```typescript
+const latest = await brain.versions.getLatest('user-123')
+if (latest) {
+  console.log(`Latest: v${latest.version} (${latest.tag})`)
+}
+```
+
+---
+
+### `versions.getVersionByTag(entityId, tag)` → `Promise<EntityVersion | null>`
+
+Get version by tag.
+
+```typescript
+const beta = await brain.versions.getVersionByTag('user-123', 'beta')
+```
+
+---
+
+### `versions.count(entityId)` → `Promise<number>`
+
+Count versions for an entity.
+
+```typescript
+const count = await brain.versions.count('user-123')
+console.log(`${count} versions saved`)
+```
+
+---
+
+### `versions.hasVersions(entityId)` → `Promise<boolean>`
+
+Check if entity has versions.
+
+```typescript
+if (await brain.versions.hasVersions('user-123')) {
+  console.log('Entity has version history')
+}
+```
+
+---
+
+### Auto-Versioning Augmentation
+
+Automatically create versions on entity updates.
+
+```typescript
+import { VersioningAugmentation } from '@soulcraft/brainy'
+
+// Configure auto-versioning
+const versioning = new VersioningAugmentation({
+  enabled: true,
+  onUpdate: true,           // Version on update()
+  onDelete: false,          // Don't version on delete
+  entities: ['user-*'],     // Only version users
+  excludeEntities: ['temp-*'],
+  excludeTypes: ['temporary'],
+  keepRecent: 50,           // Auto-prune old versions
+  keepTagged: true
+})
+
+// Apply augmentation
+brain.augment(versioning)
+
+// Now updates auto-create versions
+await brain.update('user-123', { name: 'New Name' })
+
+// Version automatically created!
+const versions = await brain.versions.list('user-123')
+console.log(`Auto-created version: ${versions[0].version}`)
+```
+
+**Configuration:**
+- `enabled`: `boolean` - Enable/disable augmentation
+- `onUpdate`: `boolean` - Version on entity updates
+- `onDelete`: `boolean` - Version before deletion
+- `entities`: `string[]` - Entity ID patterns (glob-style)
+- `excludeEntities`: `string[]` - Exclusion patterns
+- `types`: `string[]` - Entity types to version
+- `excludeTypes`: `string[]` - Types to exclude
+- `keepRecent`: `number` - Auto-prune to keep N versions
+- `keepTagged`: `boolean` - Always keep tagged versions
+
+**Pattern Matching:**
+- `['*']` - All entities
+- `['user-*']` - All IDs starting with "user-"
+- `['*-prod']` - All IDs ending with "-prod"
+- `['user-*', 'account-*']` - Multiple patterns
+
+---
+
+### Branch Isolation
+
+Versions are isolated per branch.
+
+```typescript
+// Save version on main
+await brain.versions.save('doc-1', { tag: 'main-v1' })
+
+// Fork and create version
+const feature = await brain.fork('feature')
+await feature.update('doc-1', { content: 'Feature update' })
+await feature.versions.save('doc-1', { tag: 'feature-v1' })
+
+// Versions are isolated
+const mainVersions = await brain.versions.list('doc-1')
+const featureVersions = await feature.versions.list('doc-1')
+
+console.log(mainVersions.length !== featureVersions.length)  // true
+```
+
+---
+
+### Architecture
+
+**Content-Addressable Storage:**
+- SHA-256 hashing for deduplication
+- Identical content = single storage blob
+- Efficient for entities with few changes
+
+**Metadata Indexing:**
+- Leverages existing MetadataIndexManager
+- Fast lookups by entity ID
+- Version number indexing
+
+**Storage Structure:**
+```
+_version:{entityId}:{versionNum}:{branch}  // Version metadata
+_version_blob:{contentHash}                // Content blob (deduplicated)
+```
+
+**Performance:**
+- Version save: O(1) if duplicate, O(log N) for index update
+- Version list: O(K) where K = version count
+- Version restore: O(log N) lookup + O(1) restore
+- Pruning: O(K) where K = versions pruned
+
+---
+
+### Examples
+
+#### Basic Versioning Workflow
+
+```typescript
+// Create entity
+await brain.add({
+  data: 'User profile',
+  id: 'user-123',
+  type: 'user',
+  metadata: { name: 'Alice', email: 'alice@example.com' }
+})
+
+// Save v1
+await brain.versions.save('user-123', { tag: 'v1.0' })
+
+// Make changes
+await brain.update('user-123', { name: 'Alice Smith' })
+
+// Save v2
+await brain.versions.save('user-123', { tag: 'v2.0' })
+
+// Compare versions
+const diff = await brain.versions.compare('user-123', 1, 2)
+
+// Restore to v1 if needed
+await brain.versions.restore('user-123', 'v1.0')
+```
+
+#### Release Management
+
+```typescript
+// Development workflow
+await brain.update('app-config', { version: '1.0.0-alpha' })
+await brain.versions.save('app-config', { tag: 'alpha' })
+
+await brain.update('app-config', { version: '1.0.0-beta' })
+await brain.versions.save('app-config', { tag: 'beta' })
+
+await brain.update('app-config', { version: '1.0.0' })
+await brain.versions.save('app-config', { tag: 'release' })
+
+// Rollback to beta if issues found
+await brain.versions.restore('app-config', 'beta')
+```
+
+#### Audit Trail
+
+```typescript
+// Track all changes
+const versioning = new VersioningAugmentation({
+  enabled: true,
+  onUpdate: true,
+  entities: ['audit-*'],
+  keepRecent: 100  // Keep 100 versions for audit
+})
+
+brain.augment(versioning)
+
+// All updates now tracked
+await brain.update('audit-record-1', { status: 'modified' })
+await brain.update('audit-record-1', { status: 'approved' })
+
+// View complete history
+const versions = await brain.versions.list('audit-record-1')
+versions.forEach(v => {
+  console.log(`${v.createdAt}: ${v.description}`)
+})
+```
+
+---
+
+**[📖 Complete Versioning Guide →](../features/entity-versioning.md)**
+
+---
+
 ## Virtual Filesystem (VFS)
 
 **Auto-initialized in v5.1.0!** Access via `brain.vfs` (property, not method).
 
+### Filtering VFS Entities
+
+**NEW in v5.3.0:** All VFS entities (files/folders) have `metadata.isVFSEntity: true` set automatically.
+
+Use this to filter VFS entities from semantic search results:
+
+```typescript
+// Exclude VFS entities from semantic search
+const semanticOnly = await brain.find({
+  query: 'artificial intelligence',
+  where: {
+    isVFSEntity: { notEquals: true }  // Only semantic entities
+  }
+})
+
+// Or filter to ONLY VFS entities
+const vfsOnly = await brain.find({
+  where: {
+    isVFSEntity: { equals: true }  // Only VFS files/folders
+  }
+})
+
+// Check if an entity is a VFS entity
+if (entity.metadata.isVFSEntity === true) {
+  console.log('This is a VFS file or folder')
+}
+```
+
+**Why this matters:** Without filtering, VFS files/folders can appear in concept explorers and semantic search results where they don't belong.
+
+---
+
 ### Basic File Operations
 
 #### `vfs.readFile(path, options?)` → `Promise<Buffer>`
@@ -1253,7 +1679,17 @@ const tree = await brain.vfs.getTreeStructure('/projects', {
 
 ## What's New in v5.0
 
-### v5.1.0 (Latest)
+### v5.3.0 (Latest)
+
+- ✅ **Entity Versioning** - Git-style versioning for individual entities
+- ✅ **Content-Addressable Storage** - SHA-256 deduplication for versions
+- ✅ **Auto-Versioning Augmentation** - Automatic version creation on updates
+- ✅ **Branch-Isolated Versions** - Versions isolated per branch
+- ✅ **VFS Entity Filtering** - All VFS entities now have `isVFSEntity: true` flag
+- ✅ **CRITICAL FIX:** commit() now updates branch refs correctly (brainy.ts:2385)
+- ✅ **CRITICAL FIX:** VFS entities now properly flagged for filtering
+
+### v5.1.0
 
 - ✅ **VFS Auto-Initialization** - No more separate `vfs.init()` calls
 - ✅ **VFS Property Access** - Use `brain.vfs.method()` instead of `brain.vfs().method()`

src/augmentations/versioningAugmentation.ts

@@ -0,0 +1,525 @@
+/**
+ * Versioning Augmentation (v5.3.0)
+ *
+ * Provides automatic entity versioning with configurable policies:
+ * - Auto-save on update()
+ * - Entity filtering
+ * - Retention policies
+ * - Event hooks
+ *
+ * NO MOCKS - Production implementation
+ */
+
+import { BaseAugmentation } from './brainyAugmentation.js'
+import { AugmentationManifest } from './manifest.js'
+import type { VersioningAPI } from '../versioning/VersioningAPI.js'
+import type { SaveVersionOptions } from '../versioning/VersionManager.js'
+
+export interface VersioningAugmentationConfig {
+  /** Enable auto-versioning */
+  enabled?: boolean
+
+  /** Auto-save on update() operations */
+  onUpdate?: boolean
+
+  /** Auto-save on add() operations (rarely needed) */
+  onAdd?: boolean
+
+  /** Entity ID patterns to version (glob patterns) */
+  entities?: string[]
+
+  /** Entity ID patterns to exclude (glob patterns) */
+  excludeEntities?: string[]
+
+  /** Entity types to version */
+  types?: string[]
+
+  /** Entity types to exclude */
+  excludeTypes?: string[]
+
+  /** Retention policy: Keep N recent versions per entity */
+  keepRecent?: number
+
+  /** Retention policy: Keep versions newer than timestamp */
+  keepAfter?: number
+
+  /** Retention policy: Keep tagged versions (default: true) */
+  keepTagged?: boolean
+
+  /** Tag prefix for auto-generated versions (default: 'auto-') */
+  tagPrefix?: string
+
+  /** Auto-prune old versions after save */
+  autoPrune?: boolean
+
+  /** Prune interval in milliseconds (default: 1 hour) */
+  pruneInterval?: number
+
+  /** Event hooks */
+  hooks?: {
+    /** Called before saving version */
+    beforeSave?: (entityId: string, options: SaveVersionOptions) => Promise<SaveVersionOptions | null>
+
+    /** Called after saving version */
+    afterSave?: (entityId: string, version: any) => Promise<void>
+
+    /** Called before pruning */
+    beforePrune?: (entityId: string) => Promise<boolean>
+
+    /** Called after pruning */
+    afterPrune?: (entityId: string, deleted: number) => Promise<void>
+  }
+}
+
+/**
+ * Versioning Augmentation
+ *
+ * Automatically versions entities based on configurable policies.
+ */
+export class VersioningAugmentation extends BaseAugmentation {
+  readonly name = 'versioning'
+  readonly timing = 'after' as const  // Run after operations complete
+  readonly metadata = 'readonly' as const
+  operations = ['update', 'add'] as any  // Version on update/add
+  readonly priority = 50  // Medium priority
+
+  // Augmentation metadata
+  readonly category = 'core' as const
+  readonly description = 'Automatic entity versioning with configurable retention policies'
+
+  private versioningAPI?: VersioningAPI
+  private brain?: any  // Brainy instance for entity fetching
+  private pruneTimer?: NodeJS.Timeout
+  private versionCount = 0
+
+  constructor(config: VersioningAugmentationConfig = {}) {
+    super(config)
+
+    // Merge with defaults
+    this.config = {
+      enabled: config.enabled ?? true,
+      onUpdate: config.onUpdate ?? true,
+      onAdd: config.onAdd ?? false,
+      entities: config.entities ?? ['*'],  // Version all entities by default
+      excludeEntities: config.excludeEntities ?? ['_version:*'],  // Exclude version metadata entities
+      types: config.types ?? [],  // Empty = all types
+      excludeTypes: config.excludeTypes ?? [],  // No need to exclude types (versions use 'state' type)
+      keepRecent: config.keepRecent ?? 10,
+      keepTagged: config.keepTagged ?? true,
+      tagPrefix: config.tagPrefix ?? 'auto-',
+      autoPrune: config.autoPrune ?? true,
+      pruneInterval: config.pruneInterval ?? 60 * 60 * 1000,  // 1 hour
+      hooks: config.hooks ?? {}
+    }
+  }
+
+  getManifest(): AugmentationManifest {
+    return {
+      id: 'versioning',
+      name: 'Entity Versioning',
+      version: '5.3.0',
+      description: 'Automatic entity versioning with retention policies',
+      longDescription: 'Provides automatic versioning of entities on update/add operations with configurable retention policies, entity filtering, and event hooks.',
+      category: 'storage',
+      configSchema: {
+        type: 'object',
+        properties: {
+          enabled: {
+            type: 'boolean',
+            default: true,
+            description: 'Enable automatic versioning'
+          },
+          onUpdate: {
+            type: 'boolean',
+            default: true,
+            description: 'Auto-save version on update()'
+          },
+          onAdd: {
+            type: 'boolean',
+            default: false,
+            description: 'Auto-save version on add()'
+          },
+          entities: {
+            type: 'array',
+            items: { type: 'string' },
+            default: ['*'],
+            description: 'Entity ID patterns to version (glob patterns)'
+          },
+          excludeEntities: {
+            type: 'array',
+            items: { type: 'string' },
+            default: ['_version:*'],
+            description: 'Entity ID patterns to exclude (version metadata IDs start with _version:)'
+          },
+          types: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+            description: 'Entity types to version (empty = all)'
+          },
+          excludeTypes: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+            description: 'Entity types to exclude (versions use standard state type)'
+          },
+          keepRecent: {
+            type: 'number',
+            default: 10,
+            minimum: 1,
+            description: 'Keep N recent versions per entity'
+          },
+          keepTagged: {
+            type: 'boolean',
+            default: true,
+            description: 'Keep tagged versions during pruning'
+          },
+          tagPrefix: {
+            type: 'string',
+            default: 'auto-',
+            description: 'Tag prefix for auto-generated versions'
+          },
+          autoPrune: {
+            type: 'boolean',
+            default: true,
+            description: 'Automatically prune old versions'
+          },
+          pruneInterval: {
+            type: 'number',
+            default: 3600000,
+            description: 'Prune interval in milliseconds (default: 1 hour)'
+          }
+        }
+      },
+      configDefaults: {
+        enabled: true,
+        onUpdate: true,
+        onAdd: false,
+        entities: ['*'],
+        excludeEntities: ['_version:*'],
+        types: [],
+        excludeTypes: [],
+        keepRecent: 10,
+        keepTagged: true,
+        tagPrefix: 'auto-',
+        autoPrune: true,
+        pruneInterval: 3600000
+      },
+      minBrainyVersion: '5.3.0',
+      keywords: ['versioning', 'history', 'audit', 'backup'],
+      documentation: 'https://docs.brainy.dev/versioning',
+      status: 'stable',
+      performance: {
+        memoryUsage: 'low',
+        cpuUsage: 'low',
+        networkUsage: 'none'
+      },
+      features: [
+        'auto-versioning',
+        'retention-policies',
+        'entity-filtering',
+        'event-hooks'
+      ],
+      enhancedOperations: ['update', 'add'],
+      metrics: [
+        {
+          name: 'versions_created',
+          type: 'counter',
+          description: 'Total versions created by augmentation'
+        },
+        {
+          name: 'versions_pruned',
+          type: 'counter',
+          description: 'Total versions pruned by retention policies'
+        }
+      ]
+    }
+  }
+
+  async onAttach(brain: any): Promise<void> {
+    // Store brain instance for entity fetching
+    this.brain = brain
+
+    // Get VersioningAPI instance
+    this.versioningAPI = brain.versions
+
+    // Start auto-prune timer if enabled
+    if (this.config.autoPrune && this.config.pruneInterval) {
+      this.startAutoPrune()
+    }
+  }
+
+  async onDetach(): Promise<void> {
+    // Stop auto-prune timer
+    if (this.pruneTimer) {
+      clearInterval(this.pruneTimer)
+      this.pruneTimer = undefined
+    }
+  }
+
+  /**
+   * Execute method (required by BaseAugmentation)
+   */
+  async execute(operation: string, params: any[], context: any): Promise<any> {
+    // Versioning augmentation only runs in 'after' mode
+    // Actual logic is in after() method
+    return context.originalResult
+  }
+
+  /**
+   * After operation hook - auto-save versions
+   */
+  async after(operation: string, params: any[], result: any): Promise<any> {
+    if (!this.config.enabled || !this.versioningAPI) {
+      return result
+    }
+
+    // Check if we should version this operation
+    if (operation === 'update' && !this.config.onUpdate) {
+      return result
+    }
+    if (operation === 'add' && !this.config.onAdd) {
+      return result
+    }
+
+    // Extract entity ID from params
+    const entityId = this.extractEntityId(operation, params)
+    if (!entityId) {
+      return result
+    }
+
+    // Check if entity should be versioned
+    if (!(await this.shouldVersionEntity(entityId))) {
+      return result
+    }
+
+    try {
+      // Prepare save options
+      let saveOptions: SaveVersionOptions = {
+        tag: `${this.config.tagPrefix}${Date.now()}`,
+        description: `Auto-saved after ${operation}`,
+        metadata: {
+          augmentation: 'versioning',
+          operation,
+          timestamp: Date.now()
+        }
+      }
+
+      // Call before-save hook
+      if (this.config.hooks?.beforeSave) {
+        const modifiedOptions = await this.config.hooks.beforeSave(entityId, saveOptions)
+        if (modifiedOptions === null) {
+          // Hook cancelled the save
+          return result
+        }
+        saveOptions = modifiedOptions
+      }
+
+      // Save version
+      const version = await this.versioningAPI.save(entityId, saveOptions)
+      this.versionCount++
+
+      // Call after-save hook
+      if (this.config.hooks?.afterSave) {
+        await this.config.hooks.afterSave(entityId, version)
+      }
+
+      // Auto-prune if enabled
+      if (this.config.autoPrune) {
+        await this.pruneEntity(entityId)
+      }
+    } catch (error) {
+      // Don't fail the operation if versioning fails
+      console.error(`Versioning augmentation error for ${entityId}:`, error)
+    }
+
+    return result
+  }
+
+  /**
+   * Extract entity ID from operation params
+   */
+  private extractEntityId(operation: string, params: any[]): string | null {
+    if (operation === 'update') {
+      // update(id, data) or update({ id, ... })
+      if (typeof params[0] === 'string') {
+        return params[0]
+      }
+      if (params[0]?.id) {
+        return params[0].id
+      }
+    }
+
+    if (operation === 'add') {
+      // add(data) - ID might be in data or result
+      if (params[0]?.id) {
+        return params[0].id
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Check if entity should be versioned based on filters
+   */
+  private async shouldVersionEntity(entityId: string): Promise<boolean> {
+    // Check exclude patterns first (ID-based)
+    if (this.config.excludeEntities) {
+      for (const pattern of this.config.excludeEntities) {
+        if (this.matchPattern(entityId, pattern)) {
+          return false
+        }
+      }
+    }
+
+    // Check include patterns (ID-based)
+    if (this.config.entities && this.config.entities.length > 0) {
+      let matched = false
+      for (const pattern of this.config.entities) {
+        if (this.matchPattern(entityId, pattern)) {
+          matched = true
+          break
+        }
+      }
+      if (!matched) return false
+    }
+
+    // Check entity type filters (requires fetching entity)
+    if (
+      (this.config.types && this.config.types.length > 0) ||
+      (this.config.excludeTypes && this.config.excludeTypes.length > 0)
+    ) {
+      try {
+        const entity = await this.brain?.getNounMetadata?.(entityId)
+        if (!entity) return true // If can't fetch, allow versioning
+
+        const entityType = entity.type
+
+        // Check exclude types
+        if (this.config.excludeTypes && this.config.excludeTypes.includes(entityType)) {
+          return false
+        }
+
+        // Check include types
+        if (this.config.types && this.config.types.length > 0) {
+          if (!this.config.types.includes(entityType)) {
+            return false
+          }
+        }
+      } catch (error) {
+        // If can't fetch entity, allow versioning (fail open)
+        console.error(`Failed to fetch entity ${entityId} for type filtering:`, error)
+        return true
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Simple glob pattern matching
+   */
+  private matchPattern(value: string, pattern: string): boolean {
+    if (pattern === '*') return true
+    if (!pattern.includes('*')) return value === pattern
+
+    // Convert glob to regex
+    const regex = new RegExp(
+      '^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$'
+    )
+    return regex.test(value)
+  }
+
+  /**
+   * Prune old versions for an entity
+   */
+  private async pruneEntity(entityId: string): Promise<void> {
+    if (!this.versioningAPI) return
+
+    try {
+      // Call before-prune hook
+      if (this.config.hooks?.beforePrune) {
+        const shouldPrune = await this.config.hooks.beforePrune(entityId)
+        if (!shouldPrune) return
+      }
+
+      // Prune versions
+      const result = await this.versioningAPI.prune(entityId, {
+        keepRecent: this.config.keepRecent,
+        keepAfter: this.config.keepAfter,
+        keepTagged: this.config.keepTagged
+      })
+
+      // Call after-prune hook
+      if (result.deleted > 0 && this.config.hooks?.afterPrune) {
+        await this.config.hooks.afterPrune(entityId, result.deleted)
+      }
+    } catch (error) {
+      console.error(`Failed to prune versions for ${entityId}:`, error)
+    }
+  }
+
+  /**
+   * Start auto-prune timer
+   */
+  private startAutoPrune(): void {
+    if (this.pruneTimer) {
+      clearInterval(this.pruneTimer)
+    }
+
+    this.pruneTimer = setInterval(async () => {
+      await this.pruneAllEntities()
+    }, this.config.pruneInterval)
+  }
+
+  /**
+   * Prune all versioned entities
+   */
+  private async pruneAllEntities(): Promise<void> {
+    if (!this.versioningAPI) return
+
+    try {
+      // Get all versioned entities
+      const versionIndex = (this.versioningAPI as any).manager.versionIndex
+      const entities = await versionIndex.getVersionedEntities()
+
+      // Prune each entity
+      for (const entityId of entities) {
+        if (await this.shouldVersionEntity(entityId)) {
+          await this.pruneEntity(entityId)
+        }
+      }
+    } catch (error) {
+      console.error('Auto-prune failed:', error)
+    }
+  }
+
+  /**
+   * Get augmentation statistics
+   */
+  getStats(): {
+    enabled: boolean
+    versionsCreated: number
+    entitiesPattern: string[]
+    excludePattern: string[]
+    retention: number
+  } {
+    return {
+      enabled: this.config.enabled,
+      versionsCreated: this.versionCount,
+      entitiesPattern: this.config.entities || [],
+      excludePattern: this.config.excludeEntities || [],
+      retention: this.config.keepRecent || 10
+    }
+  }
+}
+
+/**
+ * Factory function for easy augmentation creation
+ */
+export function createVersioningAugmentation(
+  config: VersioningAugmentationConfig = {}
+): VersioningAugmentation {
+  return new VersioningAugmentation(config)
+}

src/brainy.ts

@@ -24,6 +24,7 @@ import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js'
 import { NeuralEntityExtractor, ExtractedEntity } from './neural/entityExtractor.js'
 import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js'
 import { VirtualFileSystem } from './vfs/VirtualFileSystem.js'
+import { VersioningAPI } from './versioning/VersioningAPI.js'
 import { MetadataIndexManager } from './utils/metadataIndex.js'
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js'
 import { CommitBuilder } from './storage/cow/CommitObject.js'
@@ -95,6 +96,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
   private _nlp?: NaturalLanguageProcessor
   private _extractor?: NeuralEntityExtractor
   private _tripleIntelligence?: TripleIntelligenceSystem
+  private _versions?: VersioningAPI
   private _vfs?: VirtualFileSystem
 
   // State
@@ -2380,7 +2382,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       const commitHash = await builder.build()
 
       // Update branch ref to point to new commit
-      await refManager.setRef(`heads/${currentBranch}`, commitHash, {
+      await refManager.setRef(currentBranch, commitHash, {
         author: options?.author || 'unknown',
         message: options?.message || 'Snapshot commit'
       })
@@ -2937,6 +2939,38 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     return this._neural
   }
 
+  /**
+   * Versioning API - Entity version control (v5.3.0)
+   *
+   * Provides entity-level versioning with:
+   * - save() - Create version of entity
+   * - restore() - Restore entity to specific version
+   * - list() - List all versions of entity
+   * - compare() - Deep diff between versions
+   * - prune() - Remove old versions (retention policies)
+   *
+   * @example
+   * ```typescript
+   * // Save current state
+   * const version = await brain.versions.save('user-123', { tag: 'v1.0' })
+   *
+   * // List versions
+   * const versions = await brain.versions.list('user-123')
+   *
+   * // Restore to previous version
+   * await brain.versions.restore('user-123', 5)
+   *
+   * // Compare versions
+   * const diff = await brain.versions.compare('user-123', 2, 5)
+   * ```
+   */
+  get versions(): VersioningAPI {
+    if (!this._versions) {
+      this._versions = new VersioningAPI(this as any)
+    }
+    return this._versions
+  }
+
   /**
    * Natural Language Processing API
    */

src/storage/cow/RefManager.ts

@@ -119,6 +119,7 @@ export class RefManager {
     // Check if ref exists
     const existing = await this.getRef(fullName)
 
+
     // Handle createOnly
     if (options.createOnly && existing) {
       throw new Error(`Ref already exists: ${fullName}`)

src/versioning/VersionDiff.ts

@@ -0,0 +1,459 @@
+/**
+ * VersionDiff - Deep Object Comparison for Entity Versions (v5.3.0)
+ *
+ * Provides deep diff between entity versions:
+ * - Field-level change detection
+ * - Nested object comparison
+ * - Array diffing
+ * - Type change detection
+ * - Human-readable diff output
+ *
+ * NO MOCKS - Production implementation
+ */
+
+import type { NounMetadata } from '../coreTypes.js'
+
+/**
+ * Types of changes in a diff
+ */
+export type ChangeType = 'added' | 'removed' | 'modified' | 'type-changed'
+
+/**
+ * A single field change in a diff
+ */
+export interface FieldChange {
+  /** Path to the field (e.g., 'metadata.user.name') */
+  path: string
+
+  /** Type of change */
+  type: ChangeType
+
+  /** Old value (undefined for 'added') */
+  oldValue?: any
+
+  /** New value (undefined for 'removed') */
+  newValue?: any
+
+  /** Old type (for 'type-changed') */
+  oldType?: string
+
+  /** New type (for 'type-changed') */
+  newType?: string
+}
+
+/**
+ * Complete diff between two versions
+ */
+export interface VersionDiff {
+  /** Entity ID being compared */
+  entityId: string
+
+  /** From version number */
+  fromVersion: number
+
+  /** To version number */
+  toVersion: number
+
+  /** Fields that were added */
+  added: FieldChange[]
+
+  /** Fields that were removed */
+  removed: FieldChange[]
+
+  /** Fields that were modified */
+  modified: FieldChange[]
+
+  /** Fields whose type changed */
+  typeChanged: FieldChange[]
+
+  /** Total number of changes */
+  totalChanges: number
+
+  /** Whether versions are identical */
+  identical: boolean
+}
+
+/**
+ * Options for diff comparison
+ */
+export interface DiffOptions {
+  /** Entity ID (for context in output) */
+  entityId: string
+
+  /** From version number */
+  fromVersion: number
+
+  /** To version number */
+  toVersion: number
+
+  /** Ignore these fields in comparison */
+  ignoreFields?: string[]
+
+  /** Maximum depth for nested object comparison (default: 10) */
+  maxDepth?: number
+
+  /** Include unchanged fields in output (default: false) */
+  includeUnchanged?: boolean
+}
+
+/**
+ * Compare two entity versions and generate diff
+ *
+ * @param from Old version entity
+ * @param to New version entity
+ * @param options Diff options
+ * @returns Diff between versions
+ */
+export function compareEntityVersions(
+  from: NounMetadata,
+  to: NounMetadata,
+  options: DiffOptions
+): VersionDiff {
+  const added: FieldChange[] = []
+  const removed: FieldChange[] = []
+  const modified: FieldChange[] = []
+  const typeChanged: FieldChange[] = []
+
+  const ignoreFields = new Set(options.ignoreFields || [])
+  const maxDepth = options.maxDepth ?? 10
+
+  // Compare objects recursively
+  compareObjects(from, to, '', added, removed, modified, typeChanged, ignoreFields, 0, maxDepth)
+
+  const totalChanges = added.length + removed.length + modified.length + typeChanged.length
+  const identical = totalChanges === 0
+
+  return {
+    entityId: options.entityId,
+    fromVersion: options.fromVersion,
+    toVersion: options.toVersion,
+    added,
+    removed,
+    modified,
+    typeChanged,
+    totalChanges,
+    identical
+  }
+}
+
+/**
+ * Recursively compare two objects
+ */
+function compareObjects(
+  from: any,
+  to: any,
+  path: string,
+  added: FieldChange[],
+  removed: FieldChange[],
+  modified: FieldChange[],
+  typeChanged: FieldChange[],
+  ignoreFields: Set<string>,
+  depth: number,
+  maxDepth: number
+): void {
+  if (depth >= maxDepth) {
+    // Hit max depth - treat as single value
+    if (!deepEqual(from, to)) {
+      modified.push({
+        path,
+        type: 'modified',
+        oldValue: from,
+        newValue: to
+      })
+    }
+    return
+  }
+
+  // Get all keys from both objects
+  const fromKeys = new Set(Object.keys(from || {}))
+  const toKeys = new Set(Object.keys(to || {}))
+  const allKeys = new Set([...fromKeys, ...toKeys])
+
+  for (const key of allKeys) {
+    const fieldPath = path ? `${path}.${key}` : key
+
+    // Skip ignored fields
+    if (ignoreFields.has(fieldPath) || ignoreFields.has(key)) {
+      continue
+    }
+
+    const fromHas = fromKeys.has(key)
+    const toHas = toKeys.has(key)
+
+    if (!fromHas && toHas) {
+      // Field added
+      added.push({
+        path: fieldPath,
+        type: 'added',
+        newValue: to[key]
+      })
+    } else if (fromHas && !toHas) {
+      // Field removed
+      removed.push({
+        path: fieldPath,
+        type: 'removed',
+        oldValue: from[key]
+      })
+    } else {
+      // Field exists in both - check for changes
+      const fromValue = from[key]
+      const toValue = to[key]
+
+      const fromType = getValueType(fromValue)
+      const toType = getValueType(toValue)
+
+      if (fromType !== toType) {
+        // Type changed
+        typeChanged.push({
+          path: fieldPath,
+          type: 'type-changed',
+          oldValue: fromValue,
+          newValue: toValue,
+          oldType: fromType,
+          newType: toType
+        })
+      } else if (fromType === 'object' && toType === 'object') {
+        // Recursively compare nested objects
+        compareObjects(
+          fromValue,
+          toValue,
+          fieldPath,
+          added,
+          removed,
+          modified,
+          typeChanged,
+          ignoreFields,
+          depth + 1,
+          maxDepth
+        )
+      } else if (fromType === 'array' && toType === 'array') {
+        // Compare arrays
+        if (!arraysEqual(fromValue, toValue)) {
+          modified.push({
+            path: fieldPath,
+            type: 'modified',
+            oldValue: fromValue,
+            newValue: toValue
+          })
+        }
+      } else {
+        // Primitive value comparison
+        if (!deepEqual(fromValue, toValue)) {
+          modified.push({
+            path: fieldPath,
+            type: 'modified',
+            oldValue: fromValue,
+            newValue: toValue
+          })
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Get human-readable type of a value
+ */
+function getValueType(value: any): string {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}
+
+/**
+ * Deep equality check
+ */
+function deepEqual(a: any, b: any): boolean {
+  if (a === b) return true
+  if (a === null || b === null) return false
+  if (a === undefined || b === undefined) return false
+
+  const typeA = getValueType(a)
+  const typeB = getValueType(b)
+
+  if (typeA !== typeB) return false
+
+  if (typeA === 'array') {
+    return arraysEqual(a, b)
+  }
+
+  if (typeA === 'object') {
+    return objectsEqual(a, b)
+  }
+
+  // Primitive comparison
+  return a === b
+}
+
+/**
+ * Compare arrays for equality
+ */
+function arraysEqual(a: any[], b: any[]): boolean {
+  if (a.length !== b.length) return false
+
+  for (let i = 0; i < a.length; i++) {
+    if (!deepEqual(a[i], b[i])) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Compare objects for equality
+ */
+function objectsEqual(a: any, b: any): boolean {
+  const keysA = Object.keys(a)
+  const keysB = Object.keys(b)
+
+  if (keysA.length !== keysB.length) return false
+
+  for (const key of keysA) {
+    if (!keysB.includes(key)) return false
+    if (!deepEqual(a[key], b[key])) return false
+  }
+
+  return true
+}
+
+/**
+ * Format diff as human-readable string
+ *
+ * @param diff Diff to format
+ * @returns Formatted string
+ */
+export function formatDiff(diff: VersionDiff): string {
+  const lines: string[] = []
+
+  lines.push(`Diff: ${diff.entityId} v${diff.fromVersion} → v${diff.toVersion}`)
+  lines.push('')
+
+  if (diff.identical) {
+    lines.push('No changes')
+    return lines.join('\n')
+  }
+
+  lines.push(`Total changes: ${diff.totalChanges}`)
+  lines.push('')
+
+  if (diff.added.length > 0) {
+    lines.push(`Added (${diff.added.length}):`)
+    for (const change of diff.added) {
+      lines.push(`  + ${change.path}: ${formatValue(change.newValue)}`)
+    }
+    lines.push('')
+  }
+
+  if (diff.removed.length > 0) {
+    lines.push(`Removed (${diff.removed.length}):`)
+    for (const change of diff.removed) {
+      lines.push(`  - ${change.path}: ${formatValue(change.oldValue)}`)
+    }
+    lines.push('')
+  }
+
+  if (diff.modified.length > 0) {
+    lines.push(`Modified (${diff.modified.length}):`)
+    for (const change of diff.modified) {
+      lines.push(`  ~ ${change.path}:`)
+      lines.push(`      ${formatValue(change.oldValue)}`)
+      lines.push(`    → ${formatValue(change.newValue)}`)
+    }
+    lines.push('')
+  }
+
+  if (diff.typeChanged.length > 0) {
+    lines.push(`Type Changed (${diff.typeChanged.length}):`)
+    for (const change of diff.typeChanged) {
+      lines.push(`  ! ${change.path}: ${change.oldType} → ${change.newType}`)
+      lines.push(`      ${formatValue(change.oldValue)}`)
+      lines.push(`    → ${formatValue(change.newValue)}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Format value for display
+ */
+function formatValue(value: any): string {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (typeof value === 'string') return `"${value}"`
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value)
+    } catch {
+      return '[Object]'
+    }
+  }
+  return String(value)
+}
+
+/**
+ * Get summary statistics about a diff
+ */
+export function getDiffStats(diff: VersionDiff): {
+  changedFields: number
+  addedFields: number
+  removedFields: number
+  modifiedFields: number
+  typeChangedFields: number
+} {
+  return {
+    changedFields: diff.totalChanges,
+    addedFields: diff.added.length,
+    removedFields: diff.removed.length,
+    modifiedFields: diff.modified.length,
+    typeChangedFields: diff.typeChanged.length
+  }
+}
+
+/**
+ * Check if diff has any changes
+ */
+export function hasChanges(diff: VersionDiff): boolean {
+  return !diff.identical
+}
+
+/**
+ * Get all changed field paths
+ */
+export function getChangedPaths(diff: VersionDiff): string[] {
+  const paths = new Set<string>()
+
+  for (const change of diff.added) paths.add(change.path)
+  for (const change of diff.removed) paths.add(change.path)
+  for (const change of diff.modified) paths.add(change.path)
+  for (const change of diff.typeChanged) paths.add(change.path)
+
+  return Array.from(paths).sort()
+}
+
+/**
+ * Filter diff to only include specific paths
+ */
+export function filterDiff(diff: VersionDiff, paths: string[]): VersionDiff {
+  const pathSet = new Set(paths)
+
+  const filterChanges = (changes: FieldChange[]) =>
+    changes.filter((c) => pathSet.has(c.path) || paths.some((p) => c.path.startsWith(p + '.')))
+
+  const added = filterChanges(diff.added)
+  const removed = filterChanges(diff.removed)
+  const modified = filterChanges(diff.modified)
+  const typeChanged = filterChanges(diff.typeChanged)
+
+  return {
+    ...diff,
+    added,
+    removed,
+    modified,
+    typeChanged,
+    totalChanges: added.length + removed.length + modified.length + typeChanged.length,
+    identical: added.length + removed.length + modified.length + typeChanged.length === 0
+  }
+}

src/versioning/VersionIndex.ts

@@ -0,0 +1,338 @@
+/**
+ * VersionIndex - Fast Version Lookup Using Existing Index Infrastructure (v5.3.0)
+ *
+ * Integrates with Brainy's existing index system:
+ * - Uses MetadataIndexManager for field indexing
+ * - Leverages UnifiedCache for memory management
+ * - Uses EntityIdMapper for efficient ID handling
+ * - Uses ChunkManager for adaptive chunking
+ * - Leverages Roaring Bitmaps for fast set operations
+ *
+ * Version metadata is stored as regular entities with type='_version'
+ * This allows us to use existing index infrastructure without modification!
+ *
+ * Fields indexed:
+ * - versionEntityId: Entity being versioned
+ * - versionBranch: Branch version was created on
+ * - versionNumber: Version number
+ * - versionTag: Optional user tag
+ * - versionTimestamp: Creation timestamp
+ * - versionCommitHash: Commit hash
+ *
+ * NO MOCKS - Production implementation
+ */
+
+import { BaseStorage } from '../storage/baseStorage.js'
+import type { EntityVersion } from './VersionManager.js'
+import type { VersionQuery } from './VersionManager.js'
+
+/**
+ * VersionIndex - Version lookup and querying using existing indexes
+ *
+ * Strategy: Store version metadata as special entities with type='_version'
+ * This leverages ALL existing index infrastructure automatically!
+ */
+export class VersionIndex {
+  private brain: any  // Brainy instance
+  private initialized: boolean = false
+
+  constructor(brain: any) {
+    this.brain = brain
+  }
+
+  /**
+   * Initialize version index
+   *
+   * No special setup needed - we use existing entity storage and indexes!
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return
+    this.initialized = true
+  }
+
+  /**
+   * Add version to index
+   *
+   * Stores version metadata as a special entity with type='_version'
+   * This automatically indexes it using existing MetadataIndexManager!
+   *
+   * @param version Version metadata
+   */
+  async addVersion(version: EntityVersion): Promise<void> {
+    await this.initialize()
+
+    // Generate unique ID for version entity
+    const versionEntityId = this.getVersionEntityId(
+      version.entityId,
+      version.version,
+      version.branch
+    )
+
+    // Store as special entity with type='state' (version is a snapshot/state)
+    // This automatically gets indexed by MetadataIndexManager!
+    await this.brain.saveNounMetadata(versionEntityId, {
+      id: versionEntityId,
+      type: 'state', // Use standard 'state' type (version = snapshot state)
+      name: `Version ${version.version} of ${version.entityId}`,
+      metadata: {
+        // Flag to identify as version metadata
+        _isVersion: true,
+
+        // These fields are automatically indexed by MetadataIndexManager
+        versionEntityId: version.entityId, // Entity being versioned
+        versionBranch: version.branch, // Branch
+        versionNumber: version.version, // Version number
+        versionTag: version.tag, // Optional tag
+        versionTimestamp: version.timestamp, // Timestamp (indexed with bucketing)
+        versionCommitHash: version.commitHash, // Commit hash
+        versionContentHash: version.contentHash, // Content hash
+        versionAuthor: version.author, // Author
+        versionDescription: version.description, // Description
+        versionMetadata: version.metadata // Additional metadata
+      }
+    })
+  }
+
+  /**
+   * Get versions for an entity
+   *
+   * Uses existing MetadataIndexManager to query efficiently!
+   *
+   * @param query Version query
+   * @returns List of versions (newest first)
+   */
+  async getVersions(query: VersionQuery): Promise<EntityVersion[]> {
+    await this.initialize()
+
+    // Build metadata filter using existing query system
+    const filters: Record<string, any> = {
+      type: 'state',
+      _isVersion: true,
+      versionEntityId: query.entityId,
+      versionBranch: query.branch
+    }
+
+    // Add optional filters
+    if (query.tag) {
+      filters.versionTag = query.tag
+    }
+
+    // Query using existing search infrastructure
+    const results = await this.brain.searchByMetadata(filters)
+
+    // Convert entities back to EntityVersion format
+    const versions: EntityVersion[] = []
+    for (const entity of results) {
+      const version = this.entityToVersion(entity)
+      if (version) {
+        // Filter by date range if specified
+        if (query.startDate && version.timestamp < query.startDate) continue
+        if (query.endDate && version.timestamp > query.endDate) continue
+
+        versions.push(version)
+      }
+    }
+
+    // Sort by version number (newest first)
+    versions.sort((a, b) => b.version - a.version)
+
+    // Apply pagination
+    const start = query.offset || 0
+    const end = query.limit ? start + query.limit : undefined
+
+    return versions.slice(start, end)
+  }
+
+  /**
+   * Get specific version
+   *
+   * @param entityId Entity ID
+   * @param version Version number
+   * @param branch Branch name
+   * @returns Version metadata or null
+   */
+  async getVersion(
+    entityId: string,
+    version: number,
+    branch: string
+  ): Promise<EntityVersion | null> {
+    await this.initialize()
+
+    const versionEntityId = this.getVersionEntityId(entityId, version, branch)
+
+    const entity = await this.brain.getNounMetadata(versionEntityId)
+    if (!entity) return null
+
+    return this.entityToVersion(entity)
+  }
+
+  /**
+   * Get version by tag
+   *
+   * @param entityId Entity ID
+   * @param tag Version tag
+   * @param branch Branch name
+   * @returns Version metadata or null
+   */
+  async getVersionByTag(
+    entityId: string,
+    tag: string,
+    branch: string
+  ): Promise<EntityVersion | null> {
+    await this.initialize()
+
+    // Query using existing metadata index
+    const results = await this.brain.searchByMetadata({
+      type: 'state',
+      _isVersion: true,
+      versionEntityId: entityId,
+      versionBranch: branch,
+      versionTag: tag
+    })
+
+    if (results.length === 0) return null
+
+    // Return first match (tags should be unique per entity/branch)
+    return this.entityToVersion(results[0])
+  }
+
+  /**
+   * Get version count for entity
+   *
+   * @param entityId Entity ID
+   * @param branch Branch name
+   * @returns Number of versions
+   */
+  async getVersionCount(entityId: string, branch: string): Promise<number> {
+    await this.initialize()
+
+    // Use existing search infrastructure
+    const results = await this.brain.searchByMetadata({
+      type: 'state',
+      _isVersion: true,
+      versionEntityId: entityId,
+      versionBranch: branch
+    })
+
+    return results.length
+  }
+
+  /**
+   * Remove version from index
+   *
+   * @param entityId Entity ID
+   * @param version Version number
+   * @param branch Branch name
+   */
+  async removeVersion(
+    entityId: string,
+    version: number,
+    branch: string
+  ): Promise<void> {
+    await this.initialize()
+
+    const versionEntityId = this.getVersionEntityId(entityId, version, branch)
+
+    // Delete version entity (automatically removed from indexes)
+    await this.brain.deleteNounMetadata(versionEntityId)
+  }
+
+  /**
+   * Convert entity to EntityVersion format
+   *
+   * @param entity Entity from storage
+   * @returns EntityVersion or null if invalid
+   */
+  private entityToVersion(entity: any): EntityVersion | null {
+    if (!entity || !entity.metadata) return null
+
+    const m = entity.metadata
+
+    if (
+      !m.versionEntityId ||
+      !m.versionBranch ||
+      m.versionNumber === undefined ||
+      !m.versionCommitHash ||
+      !m.versionContentHash ||
+      !m.versionTimestamp
+    ) {
+      return null
+    }
+
+    return {
+      version: m.versionNumber,
+      entityId: m.versionEntityId,
+      branch: m.versionBranch,
+      commitHash: m.versionCommitHash,
+      timestamp: m.versionTimestamp,
+      contentHash: m.versionContentHash,
+      tag: m.versionTag,
+      description: m.versionDescription,
+      author: m.versionAuthor,
+      metadata: m.versionMetadata
+    }
+  }
+
+  /**
+   * Generate unique ID for version entity
+   *
+   * Format: _version:{entityId}:{version}:{branch}
+   *
+   * @param entityId Entity ID
+   * @param version Version number
+   * @param branch Branch name
+   * @returns Version entity ID
+   */
+  private getVersionEntityId(
+    entityId: string,
+    version: number,
+    branch: string
+  ): string {
+    return `_version:${entityId}:${version}:${branch}`
+  }
+
+  /**
+   * Get all versioned entities (for cleanup/debugging)
+   *
+   * @returns List of entity IDs that have versions
+   */
+  async getVersionedEntities(): Promise<string[]> {
+    await this.initialize()
+
+    // Query all version entities
+    const results = await this.brain.searchByMetadata({
+      type: 'state',
+      _isVersion: true
+    })
+
+    // Extract unique entity IDs
+    const entityIds = new Set<string>()
+    for (const entity of results) {
+      const version = this.entityToVersion(entity)
+      if (version) {
+        entityIds.add(version.entityId)
+      }
+    }
+
+    return Array.from(entityIds)
+  }
+
+  /**
+   * Clear all versions for an entity
+   *
+   * @param entityId Entity ID
+   * @param branch Branch name
+   * @returns Number of versions deleted
+   */
+  async clearVersions(entityId: string, branch: string): Promise<number> {
+    await this.initialize()
+
+    const versions = await this.getVersions({ entityId, branch })
+
+    for (const version of versions) {
+      await this.removeVersion(entityId, version.version, branch)
+    }
+
+    return versions.length
+  }
+}

src/versioning/VersionManager.ts

@@ -0,0 +1,549 @@
+/**
+ * VersionManager - Entity-Level Versioning Engine (v5.3.0)
+ *
+ * Provides entity-level version control with:
+ * - save() - Create entity version
+ * - restore() - Restore entity to specific version
+ * - list() - List all versions of an entity
+ * - compare() - Deep diff between versions
+ * - prune() - Remove old versions (retention policies)
+ *
+ * Architecture:
+ * - Hybrid storage: COW commits for full snapshots + version index for fast queries
+ * - Content-addressable: SHA-256 hashing for deduplication
+ * - Space-efficient: Only stores changed data
+ * - Branch-aware: Versions tied to current branch
+ *
+ * NO MOCKS - Production implementation
+ */
+
+import { BaseStorage } from '../storage/baseStorage.js'
+import { VersionStorage } from './VersionStorage.js'
+import { VersionIndex } from './VersionIndex.js'
+import { VersionDiff, compareEntityVersions } from './VersionDiff.js'
+import type { NounMetadata } from '../coreTypes.js'
+
+export interface EntityVersion {
+  /** Version number (1-indexed, sequential per entity) */
+  version: number
+
+  /** Entity ID */
+  entityId: string
+
+  /** Branch this version was created on */
+  branch: string
+
+  /** Commit hash containing this version */
+  commitHash: string
+
+  /** Timestamp of version creation */
+  timestamp: number
+
+  /** Optional user-provided tag (e.g., 'v1.0', 'before-refactor') */
+  tag?: string
+
+  /** Optional description */
+  description?: string
+
+  /** Content hash (SHA-256 of entity data) */
+  contentHash: string
+
+  /** Author of this version */
+  author?: string
+
+  /** Metadata about the version */
+  metadata?: Record<string, any>
+}
+
+export interface VersionQuery {
+  /** Entity ID to query versions for */
+  entityId: string
+
+  /** Optional: Filter by branch (default: current branch) */
+  branch?: string
+
+  /** Optional: Limit number of versions returned */
+  limit?: number
+
+  /** Optional: Skip first N versions */
+  offset?: number
+
+  /** Optional: Filter by tag */
+  tag?: string
+
+  /** Optional: Filter by date range */
+  startDate?: number
+  endDate?: number
+}
+
+export interface SaveVersionOptions {
+  /** Optional tag for this version (e.g., 'v1.0', 'milestone-1') */
+  tag?: string
+
+  /** Optional description */
+  description?: string
+
+  /** Optional author name */
+  author?: string
+
+  /** Optional custom metadata */
+  metadata?: Record<string, any>
+
+  /** Optional: Create commit automatically (default: false) */
+  createCommit?: boolean
+
+  /** Optional: Commit message if createCommit is true */
+  commitMessage?: string
+}
+
+export interface RestoreOptions {
+  /** Optional: Create version before restoring (for undo) */
+  createSnapshot?: boolean
+
+  /** Optional: Tag for snapshot before restore */
+  snapshotTag?: string
+}
+
+export interface PruneOptions {
+  /** Keep N most recent versions (required if keepVersions not set) */
+  keepRecent?: number
+
+  /** Keep versions newer than timestamp (optional) */
+  keepAfter?: number
+
+  /** Keep tagged versions (default: true) */
+  keepTagged?: boolean
+
+  /** Dry run - don't actually delete (default: false) */
+  dryRun?: boolean
+}
+
+/**
+ * VersionManager - Core versioning engine
+ */
+export class VersionManager {
+  private brain: any  // Brainy instance
+  private versionStorage: VersionStorage
+  private versionIndex: VersionIndex
+  private initialized: boolean = false
+
+  constructor(brain: any) {
+    this.brain = brain
+    this.versionStorage = new VersionStorage(brain)
+    this.versionIndex = new VersionIndex(brain)
+  }
+
+  /**
+   * Initialize versioning system (lazy)
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return
+
+    await this.versionStorage.initialize()
+    await this.versionIndex.initialize()
+
+    this.initialized = true
+  }
+
+  /**
+   * Save a version of an entity
+   *
+   * Creates a version snapshot of the current entity state.
+   * If createCommit is true, also creates a commit containing this version.
+   *
+   * @param entityId Entity ID to version
+   * @param options Save options
+   * @returns Created version metadata
+   */
+  async save(
+    entityId: string,
+    options: SaveVersionOptions = {}
+  ): Promise<EntityVersion> {
+    await this.initialize()
+
+    // Get current entity state
+    const entity = await this.brain.getNounMetadata(entityId)
+    if (!entity) {
+      throw new Error(`Entity ${entityId} not found`)
+    }
+
+    // Get current branch
+    const currentBranch = this.brain.currentBranch
+
+    // Get next version number
+    const existingVersions = await this.versionIndex.getVersions({
+      entityId,
+      branch: currentBranch
+    })
+    const nextVersion = existingVersions.length + 1
+
+    // Calculate content hash
+    const contentHash = this.versionStorage.hashEntity(entity)
+
+    // Check for duplicate (same content as last version)
+    if (existingVersions.length > 0) {
+      const lastVersion = existingVersions[existingVersions.length - 1]
+      if (lastVersion.contentHash === contentHash) {
+        // Content unchanged - return last version instead of creating duplicate
+        return lastVersion
+      }
+    }
+
+    // Create commit if requested
+    let commitHash: string
+    if (options.createCommit) {
+      const commitMessage =
+        options.commitMessage || `Version ${nextVersion} of entity ${entityId}`
+
+      // Use brain's commit method (note: single options object)
+      await this.brain.commit({
+        message: commitMessage,
+        author: options.author,
+        metadata: {
+          versionedEntity: entityId,
+          version: nextVersion,
+          ...options.metadata
+        }
+      })
+
+      // Get the commit hash that was just created
+      const refManager = this.brain.refManager
+      const ref = await refManager.getRef(currentBranch)
+      commitHash = ref
+    } else {
+      // Use current HEAD commit
+      const refManager = this.brain.refManager
+      const ref = await refManager.getRef(currentBranch)
+      if (!ref) {
+        throw new Error(
+          `No commit exists on branch ${currentBranch}. Create a commit first or use createCommit: true`
+        )
+      }
+      commitHash = ref
+    }
+
+    // Create version metadata
+    const version: EntityVersion = {
+      version: nextVersion,
+      entityId,
+      branch: currentBranch,
+      commitHash,
+      timestamp: Date.now(),
+      contentHash,
+      tag: options.tag,
+      description: options.description,
+      author: options.author,
+      metadata: options.metadata
+    }
+
+    // Store version
+    await this.versionStorage.saveVersion(version, entity)
+    await this.versionIndex.addVersion(version)
+
+    return version
+  }
+
+  /**
+   * Get all versions of an entity
+   *
+   * @param entityId Entity ID
+   * @param query Optional query filters
+   * @returns List of versions (newest first)
+   */
+  async list(
+    entityId: string,
+    query: Partial<VersionQuery> = {}
+  ): Promise<EntityVersion[]> {
+    await this.initialize()
+
+    const currentBranch = this.brain.currentBranch
+
+    return this.versionIndex.getVersions({
+      entityId,
+      branch: query.branch || currentBranch,
+      limit: query.limit,
+      offset: query.offset,
+      tag: query.tag,
+      startDate: query.startDate,
+      endDate: query.endDate
+    })
+  }
+
+  /**
+   * Get a specific version of an entity
+   *
+   * @param entityId Entity ID
+   * @param version Version number (1-indexed)
+   * @returns Version metadata
+   */
+  async getVersion(
+    entityId: string,
+    version: number
+  ): Promise<EntityVersion | null> {
+    await this.initialize()
+
+    const currentBranch = this.brain.currentBranch
+    return this.versionIndex.getVersion(entityId, version, currentBranch)
+  }
+
+  /**
+   * Get version by tag
+   *
+   * @param entityId Entity ID
+   * @param tag Version tag
+   * @returns Version metadata
+   */
+  async getVersionByTag(
+    entityId: string,
+    tag: string
+  ): Promise<EntityVersion | null> {
+    await this.initialize()
+
+    const currentBranch = this.brain.currentBranch
+    return this.versionIndex.getVersionByTag(entityId, tag, currentBranch)
+  }
+
+  /**
+   * Restore entity to a specific version
+   *
+   * Overwrites current entity state with the specified version.
+   * Optionally creates a snapshot before restoring for undo capability.
+   *
+   * @param entityId Entity ID
+   * @param version Version number or tag
+   * @param options Restore options
+   * @returns Restored version metadata
+   */
+  async restore(
+    entityId: string,
+    version: number | string,
+    options: RestoreOptions = {}
+  ): Promise<EntityVersion> {
+    await this.initialize()
+
+    // Create snapshot before restoring (for undo)
+    if (options.createSnapshot) {
+      await this.save(entityId, {
+        tag: options.snapshotTag || 'before-restore',
+        description: `Snapshot before restoring to version ${version}`,
+        metadata: { restoringTo: version }
+      })
+    }
+
+    // Get target version
+    let targetVersion: EntityVersion | null
+    if (typeof version === 'number') {
+      targetVersion = await this.getVersion(entityId, version)
+    } else {
+      targetVersion = await this.getVersionByTag(entityId, version)
+    }
+
+    if (!targetVersion) {
+      throw new Error(
+        `Version ${version} not found for entity ${entityId}`
+      )
+    }
+
+    // Load versioned entity data
+    const versionedEntity = await this.versionStorage.loadVersion(targetVersion)
+    if (!versionedEntity) {
+      throw new Error(
+        `Version data not found for entity ${entityId} version ${version}`
+      )
+    }
+
+    // Restore entity in storage
+    await this.brain.saveNounMetadata(entityId, versionedEntity)
+
+    return targetVersion
+  }
+
+  /**
+   * Compare two versions of an entity
+   *
+   * @param entityId Entity ID
+   * @param fromVersion Version number or tag (older)
+   * @param toVersion Version number or tag (newer)
+   * @returns Diff between versions
+   */
+  async compare(
+    entityId: string,
+    fromVersion: number | string,
+    toVersion: number | string
+  ): Promise<VersionDiff> {
+    await this.initialize()
+
+    // Get versions
+    const fromVer =
+      typeof fromVersion === 'number'
+        ? await this.getVersion(entityId, fromVersion)
+        : await this.getVersionByTag(entityId, fromVersion)
+
+    const toVer =
+      typeof toVersion === 'number'
+        ? await this.getVersion(entityId, toVersion)
+        : await this.getVersionByTag(entityId, toVersion)
+
+    if (!fromVer) {
+      throw new Error(
+        `Version ${fromVersion} not found for entity ${entityId}`
+      )
+    }
+    if (!toVer) {
+      throw new Error(
+        `Version ${toVersion} not found for entity ${entityId}`
+      )
+    }
+
+    // Load entity data
+    const fromEntity = await this.versionStorage.loadVersion(fromVer)
+    const toEntity = await this.versionStorage.loadVersion(toVer)
+
+    if (!fromEntity || !toEntity) {
+      throw new Error('Failed to load version data for comparison')
+    }
+
+    // Compare versions
+    return compareEntityVersions(fromEntity, toEntity, {
+      fromVersion: fromVer.version,
+      toVersion: toVer.version,
+      entityId
+    })
+  }
+
+  /**
+   * Prune old versions based on retention policy
+   *
+   * @param entityId Entity ID (or '*' for all entities)
+   * @param options Prune options
+   * @returns Number of versions deleted
+   */
+  async prune(
+    entityId: string,
+    options: PruneOptions
+  ): Promise<{ deleted: number; kept: number }> {
+    await this.initialize()
+
+    if (!options.keepRecent && !options.keepAfter) {
+      throw new Error(
+        'Must specify either keepRecent or keepAfter in prune options'
+      )
+    }
+
+    const currentBranch = this.brain.currentBranch
+
+    // Get all versions
+    const versions = await this.versionIndex.getVersions({
+      entityId,
+      branch: currentBranch
+    })
+
+    // Determine which versions to keep
+    const toKeep = new Set<number>()
+    const toDelete: EntityVersion[] = []
+
+    // Keep recent versions
+    if (options.keepRecent) {
+      const recentVersions = versions.slice(0, options.keepRecent)
+      recentVersions.forEach((v) => toKeep.add(v.version))
+    }
+
+    // Keep versions after timestamp
+    if (options.keepAfter) {
+      versions
+        .filter((v) => v.timestamp >= options.keepAfter!)
+        .forEach((v) => toKeep.add(v.version))
+    }
+
+    // Keep tagged versions
+    if (options.keepTagged !== false) {
+      versions
+        .filter((v) => v.tag !== undefined)
+        .forEach((v) => toKeep.add(v.version))
+    }
+
+    // Build delete list
+    for (const version of versions) {
+      if (!toKeep.has(version.version)) {
+        toDelete.push(version)
+      }
+    }
+
+    // Dry run - just return counts
+    if (options.dryRun) {
+      return {
+        deleted: toDelete.length,
+        kept: toKeep.size
+      }
+    }
+
+    // Delete versions
+    for (const version of toDelete) {
+      await this.versionStorage.deleteVersion(version)
+      await this.versionIndex.removeVersion(
+        entityId,
+        version.version,
+        currentBranch
+      )
+    }
+
+    return {
+      deleted: toDelete.length,
+      kept: toKeep.size
+    }
+  }
+
+  /**
+   * Get version count for an entity
+   *
+   * @param entityId Entity ID
+   * @returns Number of versions
+   */
+  async getVersionCount(entityId: string): Promise<number> {
+    await this.initialize()
+
+    const currentBranch = this.brain.currentBranch
+    return this.versionIndex.getVersionCount(entityId, currentBranch)
+  }
+
+  /**
+   * Check if entity has versions
+   *
+   * @param entityId Entity ID
+   * @returns True if entity has versions
+   */
+  async hasVersions(entityId: string): Promise<boolean> {
+    const count = await this.getVersionCount(entityId)
+    return count > 0
+  }
+
+  /**
+   * Get latest version of an entity
+   *
+   * @param entityId Entity ID
+   * @returns Latest version metadata or null
+   */
+  async getLatest(entityId: string): Promise<EntityVersion | null> {
+    await this.initialize()
+
+    const versions = await this.list(entityId, { limit: 1 })
+    return versions[0] || null
+  }
+
+  /**
+   * Clear all versions for an entity
+   *
+   * @param entityId Entity ID
+   * @returns Number of versions deleted
+   */
+  async clear(entityId: string): Promise<number> {
+    await this.initialize()
+
+    const result = await this.prune(entityId, {
+      keepRecent: 0,
+      keepTagged: false
+    })
+
+    return result.deleted
+  }
+}

src/versioning/VersionStorage.ts

@@ -0,0 +1,265 @@
+/**
+ * VersionStorage - Hybrid Storage for Entity Versions (v5.3.0)
+ *
+ * Implements content-addressable storage for entity versions:
+ * - SHA-256 content hashing for deduplication
+ * - Stores versions in .brainy/versions/ directory
+ * - Integrates with COW commit system
+ * - Space-efficient: Only stores unique content
+ *
+ * Storage structure:
+ * .brainy/versions/
+ *   ├── entities/
+ *   │   └── {entityId}/
+ *   │       └── {contentHash}.json  # Entity version data
+ *   └── index/
+ *       └── {entityId}.json         # Version index (managed by VersionIndex)
+ *
+ * NO MOCKS - Production implementation
+ */
+
+import { createHash } from 'crypto'
+import { BaseStorage } from '../storage/baseStorage.js'
+import type { NounMetadata } from '../coreTypes.js'
+import type { EntityVersion } from './VersionManager.js'
+
+/**
+ * VersionStorage - Content-addressable version storage
+ */
+export class VersionStorage {
+  private brain: any  // Brainy instance
+  private initialized: boolean = false
+
+  constructor(brain: any) {
+    this.brain = brain
+  }
+
+  /**
+   * Initialize version storage directories
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return
+
+    // Version storage uses the same storage adapter as the main database
+    // Directories are created automatically by the storage adapter
+
+    this.initialized = true
+  }
+
+  /**
+   * Calculate SHA-256 hash of entity content
+   *
+   * Used for content-addressable storage and deduplication
+   *
+   * @param entity Entity to hash
+   * @returns SHA-256 hash (hex string)
+   */
+  hashEntity(entity: NounMetadata): string {
+    // Create stable JSON representation (sorted keys)
+    const stableJson = this.toStableJson(entity)
+    return createHash('sha256').update(stableJson).digest('hex')
+  }
+
+  /**
+   * Convert entity to stable JSON (sorted keys for consistent hashing)
+   */
+  private toStableJson(obj: any): string {
+    if (obj === null) return 'null'
+    if (obj === undefined) return 'undefined'
+    if (typeof obj !== 'object') return JSON.stringify(obj)
+
+    if (Array.isArray(obj)) {
+      const items = obj.map((item) => this.toStableJson(item))
+      return `[${items.join(',') }]`
+    }
+
+    // Sort object keys for stable hashing
+    const sortedKeys = Object.keys(obj).sort()
+    const pairs = sortedKeys.map((key) => {
+      const value = this.toStableJson(obj[key])
+      return `"${key}":${value}`
+    })
+
+    return `{${pairs.join(',')}}`
+  }
+
+  /**
+   * Save entity version to content-addressable storage
+   *
+   * @param version Version metadata
+   * @param entity Entity data
+   */
+  async saveVersion(
+    version: EntityVersion,
+    entity: NounMetadata
+  ): Promise<void> {
+    await this.initialize()
+
+    // Content-addressable path: .brainy/versions/entities/{entityId}/{contentHash}.json
+    const versionPath = this.getVersionPath(
+      version.entityId,
+      version.contentHash
+    )
+
+    // Check if content already exists (deduplication)
+    const exists = await this.contentExists(versionPath)
+    if (exists) {
+      // Content already stored - no need to write again
+      return
+    }
+
+    // Store entity data
+    await this.writeVersionData(versionPath, entity)
+  }
+
+  /**
+   * Load entity version from storage
+   *
+   * @param version Version metadata
+   * @returns Entity data or null if not found
+   */
+  async loadVersion(version: EntityVersion): Promise<NounMetadata | null> {
+    await this.initialize()
+
+    const versionPath = this.getVersionPath(
+      version.entityId,
+      version.contentHash
+    )
+
+    try {
+      return await this.readVersionData(versionPath)
+    } catch (error) {
+      console.error(`Failed to load version ${version.version}:`, error)
+      return null
+    }
+  }
+
+  /**
+   * Delete entity version from storage
+   *
+   * @param version Version to delete
+   */
+  async deleteVersion(version: EntityVersion): Promise<void> {
+    await this.initialize()
+
+    const versionPath = this.getVersionPath(
+      version.entityId,
+      version.contentHash
+    )
+
+    await this.deleteVersionData(versionPath)
+  }
+
+  /**
+   * Get version storage path
+   *
+   * @param entityId Entity ID
+   * @param contentHash Content hash
+   * @returns Storage path
+   */
+  private getVersionPath(entityId: string, contentHash: string): string {
+    return `versions/entities/${entityId}/${contentHash}.json`
+  }
+
+  /**
+   * Check if content exists in storage
+   *
+   * @param path Storage path
+   * @returns True if exists
+   */
+  private async contentExists(path: string): Promise<boolean> {
+    try {
+      // Use storage adapter's exists check if available
+      const adapter = this.brain.storageAdapter
+      if (adapter && typeof adapter.exists === 'function') {
+        return await adapter.exists(path)
+      }
+
+      // Fallback: Try to read and catch error
+      await this.readVersionData(path)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Write version data to storage
+   *
+   * @param path Storage path
+   * @param entity Entity data
+   */
+  private async writeVersionData(
+    path: string,
+    entity: NounMetadata
+  ): Promise<void> {
+    const adapter = this.brain.storageAdapter
+
+    if (!adapter) {
+      throw new Error('Storage adapter not available')
+    }
+
+    // Serialize entity data
+    const data = JSON.stringify(entity, null, 2)
+
+    // Write to storage using adapter
+    if (typeof adapter.writeFile === 'function') {
+      await adapter.writeFile(path, data)
+    } else if (typeof adapter.set === 'function') {
+      await adapter.set(path, data)
+    } else {
+      throw new Error('Storage adapter does not support write operations')
+    }
+  }
+
+  /**
+   * Read version data from storage
+   *
+   * @param path Storage path
+   * @returns Entity data
+   */
+  private async readVersionData(path: string): Promise<NounMetadata> {
+    const adapter = this.brain.storageAdapter
+
+    if (!adapter) {
+      throw new Error('Storage adapter not available')
+    }
+
+    // Read from storage using adapter
+    let data: string
+
+    if (typeof adapter.readFile === 'function') {
+      data = await adapter.readFile(path)
+    } else if (typeof adapter.get === 'function') {
+      data = await adapter.get(path)
+    } else {
+      throw new Error('Storage adapter does not support read operations')
+    }
+
+    // Parse entity data
+    return JSON.parse(data)
+  }
+
+  /**
+   * Delete version data from storage
+   *
+   * @param path Storage path
+   */
+  private async deleteVersionData(path: string): Promise<void> {
+    const adapter = this.brain.storageAdapter
+
+    if (!adapter) {
+      throw new Error('Storage adapter not available')
+    }
+
+    // Delete from storage using adapter
+    if (typeof adapter.deleteFile === 'function') {
+      await adapter.deleteFile(path)
+    } else if (typeof adapter.delete === 'function') {
+      await adapter.delete(path)
+    } else {
+      throw new Error('Storage adapter does not support delete operations')
+    }
+  }
+
+}

src/versioning/VersioningAPI.ts

@@ -0,0 +1,520 @@
+/**
+ * VersioningAPI - Public API for Entity Versioning (v5.3.0)
+ *
+ * User-friendly wrapper around VersionManager with:
+ * - Clean, simple API
+ * - Smart defaults
+ * - Error handling
+ * - Type safety
+ *
+ * Usage:
+ *   const version = await brain.versions.save('entity-123', { tag: 'v1.0' })
+ *   const versions = await brain.versions.list('entity-123')
+ *   await brain.versions.restore('entity-123', 5)
+ *   const diff = await brain.versions.compare('entity-123', 2, 5)
+ *
+ * NO MOCKS - Production implementation
+ */
+
+import { VersionManager } from './VersionManager.js'
+import type {
+  EntityVersion,
+  SaveVersionOptions,
+  RestoreOptions,
+  PruneOptions,
+  VersionQuery
+} from './VersionManager.js'
+import type { VersionDiff, DiffOptions } from './VersionDiff.js'
+import type { BaseStorage } from '../storage/baseStorage.js'
+
+/**
+ * VersioningAPI - User-friendly versioning interface
+ */
+export class VersioningAPI {
+  private manager: VersionManager
+  private brain: any // Brainy instance
+
+  constructor(brain: any) {
+    this.brain = brain
+    this.manager = new VersionManager(brain as BaseStorage)
+  }
+
+  /**
+   * Save current state of entity as a new version
+   *
+   * Creates a version snapshot of the current entity state.
+   * Automatically handles deduplication - if content hasn't changed,
+   * returns the last version instead of creating a duplicate.
+   *
+   * @param entityId Entity ID to version
+   * @param options Save options
+   * @returns Created (or existing) version metadata
+   *
+   * @example
+   * ```typescript
+   * // Simple save
+   * const version = await brain.versions.save('user-123')
+   *
+   * // Save with tag and description
+   * const version = await brain.versions.save('user-123', {
+   *   tag: 'v1.0',
+   *   description: 'Initial release',
+   *   author: 'alice'
+   * })
+   *
+   * // Save and create commit
+   * const version = await brain.versions.save('user-123', {
+   *   tag: 'milestone-1',
+   *   createCommit: true,
+   *   commitMessage: 'Milestone 1 complete'
+   * })
+   * ```
+   */
+  async save(
+    entityId: string,
+    options: SaveVersionOptions = {}
+  ): Promise<EntityVersion> {
+    return this.manager.save(entityId, options)
+  }
+
+  /**
+   * List all versions of an entity
+   *
+   * Returns versions sorted by version number (newest first).
+   * Supports filtering by tag, date range, and pagination.
+   *
+   * @param entityId Entity ID
+   * @param options Query options
+   * @returns List of versions (newest first)
+   *
+   * @example
+   * ```typescript
+   * // Get all versions
+   * const versions = await brain.versions.list('user-123')
+   *
+   * // Get last 10 versions
+   * const recent = await brain.versions.list('user-123', { limit: 10 })
+   *
+   * // Get tagged versions
+   * const tagged = await brain.versions.list('user-123', { tag: 'v*' })
+   *
+   * // Get versions from last 30 days
+   * const recent = await brain.versions.list('user-123', {
+   *   startDate: Date.now() - 30 * 24 * 60 * 60 * 1000
+   * })
+   * ```
+   */
+  async list(
+    entityId: string,
+    options: Partial<VersionQuery> = {}
+  ): Promise<EntityVersion[]> {
+    return this.manager.list(entityId, options)
+  }
+
+  /**
+   * Get specific version of an entity
+   *
+   * @param entityId Entity ID
+   * @param version Version number (1-indexed)
+   * @returns Version metadata or null if not found
+   *
+   * @example
+   * ```typescript
+   * const version = await brain.versions.getVersion('user-123', 5)
+   * if (version) {
+   *   console.log(`Version ${version.version} created at ${new Date(version.timestamp)}`)
+   * }
+   * ```
+   */
+  async getVersion(
+    entityId: string,
+    version: number
+  ): Promise<EntityVersion | null> {
+    return this.manager.getVersion(entityId, version)
+  }
+
+  /**
+   * Get version by tag
+   *
+   * @param entityId Entity ID
+   * @param tag Version tag
+   * @returns Version metadata or null if not found
+   *
+   * @example
+   * ```typescript
+   * const version = await brain.versions.getVersionByTag('user-123', 'v1.0')
+   * ```
+   */
+  async getVersionByTag(
+    entityId: string,
+    tag: string
+  ): Promise<EntityVersion | null> {
+    return this.manager.getVersionByTag(entityId, tag)
+  }
+
+  /**
+   * Get latest version of an entity
+   *
+   * @param entityId Entity ID
+   * @returns Latest version or null if no versions exist
+   *
+   * @example
+   * ```typescript
+   * const latest = await brain.versions.getLatest('user-123')
+   * ```
+   */
+  async getLatest(entityId: string): Promise<EntityVersion | null> {
+    return this.manager.getLatest(entityId)
+  }
+
+  /**
+   * Get version content without restoring
+   *
+   * Allows you to preview version data without modifying the current entity.
+   *
+   * @param entityId Entity ID
+   * @param version Version number or tag
+   * @returns Version content
+   *
+   * @example
+   * ```typescript
+   * // Preview version 5 without restoring
+   * const oldData = await brain.versions.getContent('user-123', 5)
+   * console.log('Version 5 had name:', oldData.name)
+   *
+   * // Compare with current
+   * const current = await brain.getNounMetadata('user-123')
+   * console.log('Current name:', current.name)
+   * ```
+   */
+  async getContent(
+    entityId: string,
+    version: number | string
+  ): Promise<any> {
+    // Get version metadata
+    let versionMeta: EntityVersion | null
+    if (typeof version === 'number') {
+      versionMeta = await this.manager.getVersion(entityId, version)
+    } else {
+      versionMeta = await this.manager.getVersionByTag(entityId, version)
+    }
+
+    if (!versionMeta) {
+      throw new Error(
+        `Version ${version} not found for entity ${entityId}`
+      )
+    }
+
+    // Load version content
+    const versionStorage = (this.manager as any).versionStorage
+    const content = await versionStorage.loadVersion(versionMeta)
+
+    if (!content) {
+      throw new Error(
+        `Version content not found for entity ${entityId} version ${version}`
+      )
+    }
+
+    return content
+  }
+
+  /**
+   * Restore entity to a specific version
+   *
+   * Overwrites current entity state with the specified version.
+   * Optionally creates a snapshot before restoring for undo capability.
+   *
+   * @param entityId Entity ID
+   * @param version Version number or tag to restore to
+   * @param options Restore options
+   * @returns Restored version metadata
+   *
+   * @example
+   * ```typescript
+   * // Simple restore
+   * await brain.versions.restore('user-123', 5)
+   *
+   * // Restore with safety snapshot
+   * await brain.versions.restore('user-123', 5, {
+   *   createSnapshot: true,
+   *   snapshotTag: 'before-restore'
+   * })
+   *
+   * // Restore by tag
+   * await brain.versions.restore('user-123', 'v1.0')
+   * ```
+   */
+  async restore(
+    entityId: string,
+    version: number | string,
+    options: RestoreOptions = {}
+  ): Promise<EntityVersion> {
+    return this.manager.restore(entityId, version, options)
+  }
+
+  /**
+   * Compare two versions of an entity
+   *
+   * Generates a deep diff showing added, removed, modified, and type-changed fields.
+   *
+   * @param entityId Entity ID
+   * @param fromVersion Version number or tag (older)
+   * @param toVersion Version number or tag (newer)
+   * @returns Diff between versions
+   *
+   * @example
+   * ```typescript
+   * // Compare version 2 to version 5
+   * const diff = await brain.versions.compare('user-123', 2, 5)
+   *
+   * console.log(`Added fields: ${diff.added.length}`)
+   * console.log(`Removed fields: ${diff.removed.length}`)
+   * console.log(`Modified fields: ${diff.modified.length}`)
+   *
+   * // Print human-readable diff
+   * import { formatDiff } from './VersionDiff.js'
+   * console.log(formatDiff(diff))
+   * ```
+   */
+  async compare(
+    entityId: string,
+    fromVersion: number | string,
+    toVersion: number | string
+  ): Promise<VersionDiff> {
+    return this.manager.compare(entityId, fromVersion, toVersion)
+  }
+
+  /**
+   * Prune old versions based on retention policy
+   *
+   * Removes old versions while preserving recent and tagged versions.
+   * Use dryRun to preview what would be deleted without actually deleting.
+   *
+   * @param entityId Entity ID (or '*' for all entities - NOT IMPLEMENTED YET)
+   * @param options Prune options
+   * @returns Count of deleted and kept versions
+   *
+   * @example
+   * ```typescript
+   * // Keep last 10 versions, delete rest
+   * const result = await brain.versions.prune('user-123', {
+   *   keepRecent: 10
+   * })
+   * console.log(`Deleted ${result.deleted} versions`)
+   *
+   * // Keep last 30 days, preserve tagged versions
+   * const result = await brain.versions.prune('user-123', {
+   *   keepAfter: Date.now() - 30 * 24 * 60 * 60 * 1000,
+   *   keepTagged: true
+   * })
+   *
+   * // Dry run - see what would be deleted
+   * const result = await brain.versions.prune('user-123', {
+   *   keepRecent: 5,
+   *   dryRun: true
+   * })
+   * console.log(`Would delete ${result.deleted} versions`)
+   * ```
+   */
+  async prune(
+    entityId: string,
+    options: PruneOptions
+  ): Promise<{ deleted: number; kept: number }> {
+    return this.manager.prune(entityId, options)
+  }
+
+  /**
+   * Get version count for an entity
+   *
+   * @param entityId Entity ID
+   * @returns Number of versions
+   *
+   * @example
+   * ```typescript
+   * const count = await brain.versions.count('user-123')
+   * console.log(`Entity has ${count} versions`)
+   * ```
+   */
+  async count(entityId: string): Promise<number> {
+    return this.manager.getVersionCount(entityId)
+  }
+
+  /**
+   * Check if entity has any versions
+   *
+   * @param entityId Entity ID
+   * @returns True if entity has versions
+   *
+   * @example
+   * ```typescript
+   * if (await brain.versions.hasVersions('user-123')) {
+   *   console.log('Entity is versioned')
+   * }
+   * ```
+   */
+  async hasVersions(entityId: string): Promise<boolean> {
+    return this.manager.hasVersions(entityId)
+  }
+
+  /**
+   * Clear all versions for an entity
+   *
+   * WARNING: This permanently deletes all version history!
+   *
+   * @param entityId Entity ID
+   * @returns Number of versions deleted
+   *
+   * @example
+   * ```typescript
+   * const deleted = await brain.versions.clear('user-123')
+   * console.log(`Deleted ${deleted} versions`)
+   * ```
+   */
+  async clear(entityId: string): Promise<number> {
+    return this.manager.clear(entityId)
+  }
+
+  // ===== CONVENIENCE METHODS =====
+
+  /**
+   * Quick save with auto-generated tag
+   *
+   * Generates tag in format: 'auto-{timestamp}'
+   *
+   * @param entityId Entity ID
+   * @param description Optional description
+   * @returns Created version
+   */
+  async quickSave(
+    entityId: string,
+    description?: string
+  ): Promise<EntityVersion> {
+    return this.save(entityId, {
+      tag: `auto-${Date.now()}`,
+      description
+    })
+  }
+
+  /**
+   * Undo last change (restore to previous version)
+   *
+   * Safely restores to previous version with automatic snapshot.
+   *
+   * @param entityId Entity ID
+   * @returns Restored version metadata
+   */
+  async undo(entityId: string): Promise<EntityVersion | null> {
+    const versions = await this.list(entityId, { limit: 2 })
+
+    if (versions.length < 2) {
+      // No previous version to restore to
+      return null
+    }
+
+    const previousVersion = versions[1] // Second most recent
+
+    return this.restore(entityId, previousVersion.version, {
+      createSnapshot: true,
+      snapshotTag: 'before-undo'
+    })
+  }
+
+  /**
+   * Get version history summary
+   *
+   * @param entityId Entity ID
+   * @returns Summary statistics
+   */
+  async history(entityId: string): Promise<{
+    total: number
+    oldest?: EntityVersion
+    newest?: EntityVersion
+    tagged: number
+    branches: string[]
+  }> {
+    const versions = await this.list(entityId)
+
+    const tagged = versions.filter((v) => v.tag !== undefined).length
+    const branches = [...new Set(versions.map((v) => v.branch))]
+
+    return {
+      total: versions.length,
+      oldest: versions[versions.length - 1],
+      newest: versions[0],
+      tagged,
+      branches
+    }
+  }
+
+  /**
+   * Revert to previous version (alias for undo with better semantics)
+   *
+   * Restores entity to the previous version with automatic safety snapshot.
+   *
+   * @param entityId Entity ID
+   * @returns Restored version or null if not possible
+   *
+   * @example
+   * ```typescript
+   * // Made a mistake? Revert!
+   * await brain.update('user-123', { name: 'Wrong Name' })
+   * await brain.versions.revert('user-123')  // Back to previous state
+   * ```
+   */
+  async revert(entityId: string): Promise<EntityVersion | null> {
+    return this.undo(entityId)
+  }
+
+  /**
+   * Tag an existing version
+   *
+   * Updates the tag of an existing version.
+   * Note: This creates a new version with the tag, not modifying the existing one.
+   *
+   * @param entityId Entity ID
+   * @param version Version number
+   * @param tag New tag
+   * @returns Updated version
+   */
+  async tag(
+    entityId: string,
+    version: number,
+    tag: string
+  ): Promise<EntityVersion> {
+    // Get the version
+    const existingVersion = await this.getVersion(entityId, version)
+    if (!existingVersion) {
+      throw new Error(`Version ${version} not found for entity ${entityId}`)
+    }
+
+    // Create new version with tag
+    // Note: This is a limitation - we can't modify existing versions
+    // because they're immutable. Instead, we create a new version.
+    return this.save(entityId, {
+      tag,
+      description: `Tagged version ${version} as ${tag}`,
+      metadata: { originalVersion: version }
+    })
+  }
+
+  /**
+   * Get diff between entity's current state and a version
+   *
+   * @param entityId Entity ID
+   * @param version Version to compare against
+   * @returns Diff showing changes
+   */
+  async diffWithCurrent(
+    entityId: string,
+    version: number | string
+  ): Promise<VersionDiff> {
+    // Save current state (will be deduplicated if unchanged)
+    const currentVersion = await this.save(entityId, {
+      tag: 'temp-compare',
+      description: 'Temporary version for comparison'
+    })
+
+    // Compare
+    return this.compare(entityId, version, currentVersion.version)
+  }
+}

src/vfs/VirtualFileSystem.ts

@@ -209,7 +209,8 @@ export class VirtualFileSystem implements IVirtualFileSystem {
             path: '/',
             name: '',
             vfsType: 'directory',
-            isVFS: true,  // v4.3.3: Mark as VFS entity
+            isVFS: true,  // v4.3.3: Mark as VFS entity (internal)
+            isVFSEntity: true,  // v5.3.0: Explicit flag for developer filtering
             size: 0,
             permissions: 0o755,
             owner: 'root',
@@ -231,7 +232,8 @@ export class VirtualFileSystem implements IVirtualFileSystem {
         path: '/',
         name: '',
         vfsType: 'directory',
-        isVFS: true,  // v4.3.3: Mark as VFS entity
+        isVFS: true,  // v4.3.3: Mark as VFS entity (internal)
+        isVFSEntity: true,  // v5.3.0: Explicit flag for developer filtering
         size: 0,
         permissions: 0o755,
         owner: 'root',
@@ -357,7 +359,8 @@ export class VirtualFileSystem implements IVirtualFileSystem {
       name,
       parent: parentId,
       vfsType: 'file',
-      isVFS: true,  // v4.3.3: Mark as VFS entity
+      isVFS: true,  // v4.3.3: Mark as VFS entity (internal)
+      isVFSEntity: true,  // v5.3.0: Explicit flag for developer filtering
       size: buffer.length,
       mimeType,
       extension: this.getExtension(name),
@@ -713,7 +716,8 @@ export class VirtualFileSystem implements IVirtualFileSystem {
         name,
         parent: parentId,
         vfsType: 'directory',
-        isVFS: true,  // v4.3.3: Mark as VFS entity
+        isVFS: true,  // v4.3.3: Mark as VFS entity (internal)
+        isVFSEntity: true,  // v5.3.0: Explicit flag for developer filtering
         size: 0,
         permissions: options?.mode || this.config.permissions?.defaultDirectory || 0o755,
         owner: 'user',

src/vfs/types.ts

@@ -33,7 +33,8 @@ export interface VFSMetadata {
   name: string                    // Filename or directory name
   parent?: string                 // Parent directory entity ID
   vfsType: 'file' | 'directory' | 'symlink'
-  isVFS?: boolean                 // v4.3.3: Mark as VFS entity (separates from knowledge graph)
+  isVFS?: boolean                 // v4.3.3: Mark as VFS entity (internal, separates from knowledge graph)
+  isVFSEntity?: boolean           // v5.3.0: Explicit developer-facing flag for filtering VFS entities
 
   // File attributes
   size: number                    // Size in bytes (0 for directories)

tests/integration/commit-ref-bug.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Integration test to reproduce commit() ref update bug
+ * Bug: commit() creates blobs but doesn't update branch refs
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { Brainy } from '../../src/brainy.js'
+import * as fs from 'fs'
+import * as path from 'path'
+import * as zlib from 'zlib'
+
+const TEST_DATA_PATH = './test-commit-ref-bug-data'
+
+describe('Commit Ref Update Bug (v5.2.0)', () => {
+  let brain: Brainy
+
+  beforeEach(async () => {
+    // Clean up test data
+    if (fs.existsSync(TEST_DATA_PATH)) {
+      fs.rmSync(TEST_DATA_PATH, { recursive: true, force: true })
+    }
+
+    brain = new Brainy({
+      storage: {
+        type: 'filesystem',
+        path: TEST_DATA_PATH,
+        branch: 'main',
+        enableCompression: true
+      },
+      silent: false  // Enable logging
+    })
+
+    await brain.init()
+  })
+
+  afterEach(() => {
+    if (fs.existsSync(TEST_DATA_PATH)) {
+      fs.rmSync(TEST_DATA_PATH, { recursive: true, force: true })
+    }
+  })
+
+  it('should update branch ref after commit', async () => {
+    // Add an entity
+    await brain.add({
+      data: 'Test entity',
+      type: 'concept',
+      metadata: { test: true }
+    })
+
+    // Create first commit
+    const commit1Hash = await brain.commit({
+      message: 'First commit',
+      author: 'test@example.com'
+    })
+
+    console.log(`\n=== Commit 1 created: ${commit1Hash} ===`)
+
+    // Check the ref file directly
+    const refPath = path.join(TEST_DATA_PATH, '_cow', 'ref:refs', 'heads', 'main.gz')
+
+    expect(fs.existsSync(refPath), 'Ref file should exist').toBe(true)
+
+    const refContent1 = JSON.parse(
+      zlib.gunzipSync(fs.readFileSync(refPath)).toString()
+    )
+
+    console.log('Ref after commit 1:', {
+      commitHash: refContent1.commitHash,
+      updatedAt: new Date(refContent1.updatedAt).toISOString()
+    })
+
+    // THIS IS THE BUG: commitHash should equal commit1Hash
+    expect(refContent1.commitHash).toBe(commit1Hash)
+    expect(refContent1.commitHash).not.toBe('0'.repeat(64))
+
+    // Add another entity
+    await brain.add({
+      data: 'Second entity',
+      type: 'concept'
+    })
+
+    // Create second commit
+    const commit2Hash = await brain.commit({
+      message: 'Second commit',
+      author: 'test@example.com'
+    })
+
+    console.log(`\n=== Commit 2 created: ${commit2Hash} ===`)
+
+    // Check ref again
+    const refContent2 = JSON.parse(
+      zlib.gunzipSync(fs.readFileSync(refPath)).toString()
+    )
+
+    console.log('Ref after commit 2:', {
+      commitHash: refContent2.commitHash,
+      updatedAt: new Date(refContent2.updatedAt).toISOString()
+    })
+
+    // THIS IS THE BUG: commitHash should equal commit2Hash
+    expect(refContent2.commitHash).toBe(commit2Hash)
+    expect(refContent2.updatedAt).toBeGreaterThan(refContent1.updatedAt)
+  })
+})

tests/integration/versioning.test.ts

@@ -0,0 +1,409 @@
+/**
+ * Entity Versioning Integration Tests (v5.3.0)
+ *
+ * Tests the complete versioning workflow:
+ * - Save versions
+ * - List versions
+ * - Restore versions
+ * - Compare versions
+ * - Prune versions
+ * - Auto-versioning augmentation
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Brainy } from '../../src/brainy.js'
+import type { EntityVersion } from '../../src/versioning/VersionManager.js'
+import { VersioningAugmentation } from '../../src/augmentations/versioningAugmentation.js'
+
+describe('Entity Versioning (v5.3.0)', () => {
+  let brain: Brainy
+
+  beforeEach(async () => {
+    brain = new Brainy({
+      storage: { type: 'memory' },
+      silent: true
+    })
+    await brain.init()
+  })
+
+  describe('Core Versioning API', () => {
+    it('should save and retrieve versions', async () => {
+      // Add initial entity
+      await brain.add({
+        data: 'Alice',
+        id: 'user-123',
+        type: 'user',
+        metadata: {
+          name: 'Alice',
+          email: 'alice@example.com'
+        }
+      })
+
+      // Save version 1
+      const v1 = await brain.versions.save('user-123', {
+        tag: 'v1.0',
+        description: 'Initial version'
+      })
+
+      expect(v1.version).toBe(1)
+      expect(v1.entityId).toBe('user-123')
+      expect(v1.tag).toBe('v1.0')
+      expect(v1.contentHash).toBeDefined()
+
+      // Update entity
+      await brain.update('user-123', { name: 'Alice Smith' })
+
+      // Save version 2
+      const v2 = await brain.versions.save('user-123', {
+        tag: 'v2.0',
+        description: 'Updated name'
+      })
+
+      expect(v2.version).toBe(2)
+      expect(v2.entityId).toBe('user-123')
+
+      // List versions
+      const versions = await brain.versions.list('user-123')
+      expect(versions).toHaveLength(2)
+      expect(versions[0].version).toBe(2) // Newest first
+      expect(versions[1].version).toBe(1)
+    })
+
+    it('should deduplicate identical content', async () => {
+      await brain.add({
+        data: 'Doc',
+        id: 'doc-1',
+        type: 'document',
+        metadata: {
+          name: 'Doc',
+          content: 'Hello'
+        }
+      })
+
+      // Save version 1
+      const v1 = await brain.versions.save('doc-1', { tag: 'v1' })
+
+      // Save again without changes
+      const v2 = await brain.versions.save('doc-1', { tag: 'v2' })
+
+      // Should return existing version (same content hash)
+      expect(v2.version).toBe(v1.version)
+      expect(v2.contentHash).toBe(v1.contentHash)
+
+      // Only one version should exist
+      const versions = await brain.versions.list('doc-1')
+      expect(versions).toHaveLength(1)
+    })
+
+    it('should restore to previous version', async () => {
+      await brain.add({
+        data: 'Config',
+        id: 'config-1',
+        type: 'thing',
+        metadata: {
+          name: 'Config',
+          settings: { theme: 'light' }
+        }
+      })
+
+      // Save v1
+      await brain.versions.save('config-1', { tag: 'v1' })
+
+      // Update
+      await brain.update('config-1', { settings: { theme: 'dark' } })
+
+      // Save v2
+      await brain.versions.save('config-1', { tag: 'v2' })
+
+      // Verify current state
+      let current = await brain.getNounMetadata('config-1')
+      expect(current?.metadata?.settings?.theme).toBe('dark')
+
+      // Restore to v1
+      await brain.versions.restore('config-1', 1)
+
+      // Verify restored state
+      current = await brain.getNounMetadata('config-1')
+      expect(current?.metadata?.settings?.theme).toBe('light')
+    })
+
+    it('should compare versions', async () => {
+      await brain.add({
+        data: 'Bob',
+        id: 'user-456',
+        type: 'user',
+        metadata: {
+          name: 'Bob',
+          email: 'bob@example.com',
+          age: 30
+        }
+      })
+
+      await brain.versions.save('user-456', { tag: 'v1' })
+
+      // Update
+      await brain.update('user-456', {
+        name: 'Robert',
+        email: 'robert@example.com',
+        city: 'NYC'
+      })
+
+      await brain.versions.save('user-456', { tag: 'v2' })
+
+      // Compare versions
+      const diff = await brain.versions.compare('user-456', 1, 2)
+
+      expect(diff.totalChanges).toBeGreaterThan(0)
+      expect(diff.modified.length).toBeGreaterThan(0)
+      expect(diff.added.length).toBeGreaterThan(0)
+
+      // Check specific changes
+      const nameChange = diff.modified.find(c => c.path.includes('name'))
+      expect(nameChange).toBeDefined()
+      expect(nameChange?.oldValue).toBe('Bob')
+      expect(nameChange?.newValue).toBe('Robert')
+
+      const cityAdd = diff.added.find(c => c.path.includes('city'))
+      expect(cityAdd).toBeDefined()
+      expect(cityAdd?.newValue).toBe('NYC')
+    })
+
+    it('should get version content without restoring', async () => {
+      await brain.add({
+        data: 'Note',
+        id: 'note-1',
+        type: 'document',
+        metadata: {
+          name: 'Note',
+          content: 'Version 1'
+        }
+      })
+
+      await brain.versions.save('note-1', { tag: 'v1' })
+
+      await brain.update('note-1', { content: 'Version 2' })
+      await brain.versions.save('note-1', { tag: 'v2' })
+
+      // Get v1 content without restoring
+      const v1Content = await brain.versions.getContent('note-1', 1)
+      expect(v1Content.metadata.content).toBe('Version 1')
+
+      // Current should still be v2
+      const current = await brain.getNounMetadata('note-1')
+      expect(current?.metadata?.content).toBe('Version 2')
+    })
+
+    it('should prune old versions', async () => {
+      await brain.add({
+        data: 'Log',
+        id: 'log-1',
+        type: 'document',
+        metadata: {
+          name: 'Log'
+        }
+      })
+
+      // Create 10 versions
+      for (let i = 1; i <= 10; i++) {
+        await brain.update('log-1', { content: `Entry ${i}` })
+        await brain.versions.save('log-1', { tag: `v${i}` })
+      }
+
+      // Verify all 10 exist
+      let versions = await brain.versions.list('log-1')
+      expect(versions.length).toBeGreaterThanOrEqual(10)
+
+      // Prune to keep only 5 most recent
+      const result = await brain.versions.prune('log-1', {
+        keepRecent: 5,
+        keepTagged: false
+      })
+
+      expect(result.deleted).toBeGreaterThan(0)
+      expect(result.kept).toBe(5)
+
+      // Verify only 5 remain
+      versions = await brain.versions.list('log-1')
+      expect(versions).toHaveLength(5)
+    })
+
+    it('should support version tags', async () => {
+      await brain.add({
+        data: 'App',
+        id: 'app-1',
+        type: 'thing',
+        metadata: {
+          name: 'App'
+        }
+      })
+
+      await brain.versions.save('app-1', { tag: 'alpha' })
+      await brain.update('app-1', { version: '0.2' })
+      await brain.versions.save('app-1', { tag: 'beta' })
+      await brain.update('app-1', { version: '1.0' })
+      await brain.versions.save('app-1', { tag: 'release' })
+
+      // Get by tag
+      const beta = await brain.versions.getVersionByTag('app-1', 'beta')
+      expect(beta).toBeDefined()
+      expect(beta?.tag).toBe('beta')
+
+      // Restore by tag
+      await brain.versions.restore('app-1', 'beta')
+      const current = await brain.getNounMetadata('app-1')
+      expect(current?.metadata?.version).toBe('0.2')
+    })
+
+    it('should support undo/revert', async () => {
+      await brain.add({
+        data: 'Data',
+        id: 'data-1',
+        type: 'thing',
+        metadata: {
+          name: 'Data',
+          value: 100
+        }
+      })
+
+      await brain.versions.save('data-1')
+      await brain.update('data-1', { value: 200 })
+      await brain.versions.save('data-1')
+
+      // Make a bad change
+      await brain.update('data-1', { value: 999 })
+
+      // Undo (reverts to previous version)
+      await brain.versions.undo('data-1')
+
+      const current = await brain.getNounMetadata('data-1')
+      expect(current?.metadata?.value).toBe(200)
+
+      // Revert (alias for undo)
+      await brain.update('data-1', { value: 999 })
+      await brain.versions.revert('data-1')
+
+      const reverted = await brain.getNounMetadata('data-1')
+      expect(reverted?.metadata?.value).toBe(200)
+    })
+  })
+
+  describe('Auto-Versioning Augmentation', () => {
+    it('should auto-version on update when enabled', async () => {
+      // Add augmentation
+      const augmentation = new VersioningAugmentation({
+        enabled: true,
+        onUpdate: true,
+        entities: ['*'],
+        keepRecent: 10
+      })
+
+      brain.augment(augmentation as any)
+
+      await brain.add({
+        data: 'Auto User',
+        id: 'auto-1',
+        type: 'user',
+        metadata: {
+          name: 'Auto User'
+        }
+      })
+
+      // No versions yet
+      expect(await brain.versions.count('auto-1')).toBe(0)
+
+      // Update should auto-create version
+      await brain.update('auto-1', { name: 'Auto User Updated' })
+
+      // Give augmentation time to process
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      // Should have auto-created version
+      const count = await brain.versions.count('auto-1')
+      expect(count).toBeGreaterThan(0)
+    })
+
+    it('should filter entities by ID pattern', async () => {
+      const augmentation = new VersioningAugmentation({
+        enabled: true,
+        onUpdate: true,
+        entities: ['versioned-*'],
+        excludeEntities: ['temp-*']
+      })
+
+      brain.augment(augmentation as any)
+
+      // This should be versioned
+      await brain.add({ data: 'V1', id: 'versioned-1', type: 'thing', metadata: { name: 'V1' } })
+      await brain.update('versioned-1', { name: 'V1 Updated' })
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      // This should NOT be versioned
+      await brain.add({ data: 'O1', id: 'other-1', type: 'thing', metadata: { name: 'O1' } })
+      await brain.update('other-1', { name: 'O1 Updated' })
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      expect(await brain.versions.count('versioned-1')).toBeGreaterThan(0)
+      expect(await brain.versions.count('other-1')).toBe(0)
+    })
+  })
+
+  describe('Branch Isolation', () => {
+    it('should isolate versions by branch', async () => {
+      await brain.add({
+        data: 'Test',
+        id: 'branch-test',
+        type: 'thing',
+        metadata: {
+          name: 'Test'
+        }
+      })
+
+      // Save on main
+      await brain.versions.save('branch-test', { tag: 'main-v1' })
+
+      // Switch to feature branch
+      await brain.fork('feature')
+
+      // Update on feature
+      await brain.update('branch-test', { name: 'Feature Update' })
+      await brain.versions.save('branch-test', { tag: 'feature-v1' })
+
+      // Versions on feature branch
+      const featureVersions = await brain.versions.list('branch-test')
+      expect(featureVersions.length).toBeGreaterThan(0)
+
+      // Switch back to main
+      await brain.checkout('main')
+
+      // Versions on main branch
+      const mainVersions = await brain.versions.list('branch-test')
+
+      // Should be isolated
+      expect(mainVersions.length).not.toBe(featureVersions.length)
+    })
+  })
+
+  describe('Edge Cases', () => {
+    it('should handle non-existent entities gracefully', async () => {
+      await expect(
+        brain.versions.save('nonexistent', { tag: 'v1' })
+      ).rejects.toThrow('Entity nonexistent not found')
+    })
+
+    it('should handle empty version history', async () => {
+      await brain.add({ data: 'New', id: 'new-1', type: 'thing', metadata: { name: 'New' } })
+
+      expect(await brain.versions.count('new-1')).toBe(0)
+      expect(await brain.versions.hasVersions('new-1')).toBe(false)
+      expect(await brain.versions.getLatest('new-1')).toBeNull()
+    })
+
+    it('should handle version not found', async () => {
+      await brain.add({ data: 'Test', id: 'test-1', type: 'thing', metadata: { name: 'Test' } })
+
+      await expect(
+        brain.versions.restore('test-1', 999)
+      ).rejects.toThrow('Version 999 not found')
+    })
+  })
+})

tests/unit/versioning/VersionDiff.test.ts

@@ -0,0 +1,538 @@
+/**
+ * VersionDiff Unit Tests (v5.3.0)
+ *
+ * Tests deep object comparison:
+ * - Added fields
+ * - Removed fields
+ * - Modified fields
+ * - Type changes
+ * - Nested object comparison
+ * - Array comparison
+ */
+
+import { describe, it, expect } from 'vitest'
+import { compareEntityVersions } from '../../../src/versioning/VersionDiff.js'
+import type { NounMetadata } from '../../../src/coreTypes.js'
+
+describe('VersionDiff', () => {
+  describe('compareEntityVersions()', () => {
+    it('should detect added fields', () => {
+      const from: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: { email: 'alice@example.com' }
+      }
+
+      const to: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {
+          email: 'alice@example.com',
+          city: 'NYC',
+          age: 30
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'user-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.added.length).toBe(2)
+      expect(diff.added.some(c => c.path.includes('city'))).toBe(true)
+      expect(diff.added.some(c => c.path.includes('age'))).toBe(true)
+      expect(diff.added.find(c => c.path.includes('city'))?.newValue).toBe('NYC')
+    })
+
+    it('should detect removed fields', () => {
+      const from: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {
+          email: 'alice@example.com',
+          city: 'NYC',
+          age: 30
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: { email: 'alice@example.com' }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'user-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.removed.length).toBe(2)
+      expect(diff.removed.some(c => c.path.includes('city'))).toBe(true)
+      expect(diff.removed.some(c => c.path.includes('age'))).toBe(true)
+      expect(diff.removed.find(c => c.path.includes('city'))?.oldValue).toBe('NYC')
+    })
+
+    it('should detect modified fields', () => {
+      const from: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {
+          email: 'alice@example.com',
+          status: 'active'
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice Smith',
+        metadata: {
+          email: 'alice.smith@example.com',
+          status: 'active'
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'user-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.modified.length).toBe(2)
+
+      const nameChange = diff.modified.find(c => c.path.includes('name'))
+      expect(nameChange?.oldValue).toBe('Alice')
+      expect(nameChange?.newValue).toBe('Alice Smith')
+
+      const emailChange = diff.modified.find(c => c.path.includes('email'))
+      expect(emailChange?.oldValue).toBe('alice@example.com')
+      expect(emailChange?.newValue).toBe('alice.smith@example.com')
+    })
+
+    it('should detect type changes', () => {
+      const from: NounMetadata = {
+        id: 'config-1',
+        type: 'thing',
+        name: 'Config',
+        metadata: { value: '100' }
+      }
+
+      const to: NounMetadata = {
+        id: 'config-1',
+        type: 'thing',
+        name: 'Config',
+        metadata: { value: 100 }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'config-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.typeChanged.length).toBe(1)
+      const typeChange = diff.typeChanged[0]
+      expect(typeChange.path).toContain('value')
+      expect(typeChange.oldType).toBe('string')
+      expect(typeChange.newType).toBe('number')
+      expect(typeChange.oldValue).toBe('100')
+      expect(typeChange.newValue).toBe(100)
+    })
+
+    it('should detect identical versions', () => {
+      const entity: NounMetadata = {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Unchanged' }
+      }
+
+      const diff = compareEntityVersions(entity, entity, {
+        entityId: 'doc-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.identical).toBe(true)
+      expect(diff.totalChanges).toBe(0)
+      expect(diff.added).toHaveLength(0)
+      expect(diff.removed).toHaveLength(0)
+      expect(diff.modified).toHaveLength(0)
+    })
+
+    it('should handle nested object changes', () => {
+      const from: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {
+          address: {
+            street: '123 Main St',
+            city: 'NYC'
+          }
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {
+          address: {
+            street: '456 Oak Ave',
+            city: 'NYC',
+            zip: '10001'
+          }
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'user-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.modified.some(c => c.path.includes('address.street'))).toBe(true)
+      expect(diff.added.some(c => c.path.includes('address.zip'))).toBe(true)
+
+      const streetChange = diff.modified.find(c => c.path.includes('address.street'))
+      expect(streetChange?.oldValue).toBe('123 Main St')
+      expect(streetChange?.newValue).toBe('456 Oak Ave')
+    })
+
+    it('should handle array changes', () => {
+      const from: NounMetadata = {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: {
+          tags: ['a', 'b', 'c']
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: {
+          tags: ['a', 'b', 'd']
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'doc-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      // Array element change detected as modification
+      expect(diff.totalChanges).toBeGreaterThan(0)
+    })
+
+    it('should handle null and undefined', () => {
+      const from: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {
+          a: null,
+          b: undefined,
+          c: 'value'
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {
+          a: 'now-value',
+          b: null,
+          c: 'value'
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'test-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.totalChanges).toBeGreaterThan(0)
+    })
+
+    it('should ignore specified fields', () => {
+      const from: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {
+          email: 'alice@example.com',
+          lastModified: 1000,
+          internal: 'ignore-me'
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice Smith',
+        metadata: {
+          email: 'alice@example.com',
+          lastModified: 2000,
+          internal: 'changed'
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'user-1',
+        fromVersion: 1,
+        toVersion: 2,
+        ignoreFields: ['lastModified', 'internal']
+      })
+
+      // Should only detect name change
+      expect(diff.totalChanges).toBe(1)
+      expect(diff.modified.some(c => c.path.includes('name'))).toBe(true)
+      expect(diff.modified.some(c => c.path.includes('lastModified'))).toBe(false)
+      expect(diff.modified.some(c => c.path.includes('internal'))).toBe(false)
+    })
+
+    it('should respect maxDepth option', () => {
+      const from: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {
+          level1: {
+            level2: {
+              level3: {
+                level4: 'deep-value'
+              }
+            }
+          }
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {
+          level1: {
+            level2: {
+              level3: {
+                level4: 'changed-value'
+              }
+            }
+          }
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'test-1',
+        fromVersion: 1,
+        toVersion: 2,
+        maxDepth: 2  // Stop at level2
+      })
+
+      // Should detect change at metadata.level1.level2 level
+      expect(diff.totalChanges).toBeGreaterThan(0)
+    })
+
+    it('should handle empty objects', () => {
+      const from: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      }
+
+      const to: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: { value: 123 }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'test-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.added.length).toBe(1)
+      expect(diff.added[0].newValue).toBe(123)
+    })
+
+    it('should calculate total changes correctly', () => {
+      const from: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {
+          email: 'alice@example.com',
+          status: 'active',
+          age: 30
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice Smith',
+        metadata: {
+          email: 'alice.smith@example.com',
+          city: 'NYC'
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'user-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      const expectedTotal =
+        diff.added.length +
+        diff.removed.length +
+        diff.modified.length +
+        diff.typeChanged.length
+
+      expect(diff.totalChanges).toBe(expectedTotal)
+    })
+
+    it('should handle complex real-world changes', () => {
+      const from: NounMetadata = {
+        id: 'project-1',
+        type: 'thing',
+        name: 'My Project',
+        metadata: {
+          description: 'Old description',
+          status: 'draft',
+          team: ['alice', 'bob'],
+          config: {
+            theme: 'light',
+            notifications: true
+          },
+          createdAt: 1000
+        }
+      }
+
+      const to: NounMetadata = {
+        id: 'project-1',
+        type: 'thing',
+        name: 'My Awesome Project',
+        metadata: {
+          description: 'New description',
+          status: 'active',
+          team: ['alice', 'bob', 'charlie'],
+          config: {
+            theme: 'dark',
+            notifications: true,
+            language: 'en'
+          },
+          createdAt: 1000,
+          updatedAt: 2000
+        }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'project-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.totalChanges).toBeGreaterThan(0)
+      expect(diff.modified.length).toBeGreaterThan(0)
+      expect(diff.added.length).toBeGreaterThan(0)
+
+      const nameChange = diff.modified.find(c => c.path.includes('name'))
+      expect(nameChange?.newValue).toBe('My Awesome Project')
+    })
+
+    it('should handle boolean changes', () => {
+      const from: NounMetadata = {
+        id: 'feature-1',
+        type: 'thing',
+        name: 'Feature',
+        metadata: { enabled: false }
+      }
+
+      const to: NounMetadata = {
+        id: 'feature-1',
+        type: 'thing',
+        name: 'Feature',
+        metadata: { enabled: true }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'feature-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.modified.length).toBe(1)
+      expect(diff.modified[0].oldValue).toBe(false)
+      expect(diff.modified[0].newValue).toBe(true)
+    })
+
+    it('should handle number changes', () => {
+      const from: NounMetadata = {
+        id: 'counter-1',
+        type: 'thing',
+        name: 'Counter',
+        metadata: { count: 10 }
+      }
+
+      const to: NounMetadata = {
+        id: 'counter-1',
+        type: 'thing',
+        name: 'Counter',
+        metadata: { count: 20 }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'counter-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.modified.length).toBe(1)
+      expect(diff.modified[0].oldValue).toBe(10)
+      expect(diff.modified[0].newValue).toBe(20)
+    })
+
+    it('should handle date/timestamp changes', () => {
+      const from: NounMetadata = {
+        id: 'event-1',
+        type: 'thing',
+        name: 'Event',
+        metadata: { timestamp: 1000 }
+      }
+
+      const to: NounMetadata = {
+        id: 'event-1',
+        type: 'thing',
+        name: 'Event',
+        metadata: { timestamp: 2000 }
+      }
+
+      const diff = compareEntityVersions(from, to, {
+        entityId: 'event-1',
+        fromVersion: 1,
+        toVersion: 2
+      })
+
+      expect(diff.modified.length).toBe(1)
+      expect(diff.modified[0].path).toContain('timestamp')
+    })
+  })
+})

tests/unit/versioning/VersionManager.test.ts

@@ -0,0 +1,654 @@
+/**
+ * VersionManager Unit Tests (v5.3.0)
+ *
+ * Tests the core versioning engine in isolation:
+ * - Save versions
+ * - Restore versions
+ * - List versions
+ * - Compare versions
+ * - Prune versions
+ * - Content deduplication
+ * - Branch awareness
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { VersionManager } from '../../../src/versioning/VersionManager.js'
+import type { NounMetadata } from '../../../src/coreTypes.js'
+
+describe('VersionManager', () => {
+  let manager: VersionManager
+  let mockBrain: any
+  let mockStorage: Map<string, any>
+  let mockIndex: Map<string, any>
+
+  beforeEach(() => {
+    // Mock storage
+    mockStorage = new Map()
+    mockIndex = new Map()
+
+    // Mock Brainy instance
+    mockBrain = {
+      currentBranch: 'main',
+      storageAdapter: {
+        exists: vi.fn(async (path: string) => mockStorage.has(path)),
+        writeFile: vi.fn(async (path: string, data: string) => {
+          mockStorage.set(path, data)
+        }),
+        readFile: vi.fn(async (path: string) => {
+          const data = mockStorage.get(path)
+          if (!data) throw new Error('File not found')
+          return data
+        }),
+        deleteFile: vi.fn(async (path: string) => {
+          mockStorage.delete(path)
+        })
+      },
+      refManager: {
+        getRef: vi.fn(async (branch: string) => ({
+          name: `refs/heads/${branch}`,
+          commitHash: 'commit-hash-123',
+          type: 'branch'
+        })),
+        setRef: vi.fn(async () => {}),
+        resolveRef: vi.fn(async () => 'commit-hash-123')
+      },
+      getNounMetadata: vi.fn(async (id: string) => {
+        const entity = mockIndex.get(id)
+        if (!entity) throw new Error(`Entity ${id} not found`)
+        return entity
+      }),
+      saveNounMetadata: vi.fn(async (id: string, data: NounMetadata) => {
+        mockIndex.set(id, data)
+      }),
+      searchByMetadata: vi.fn(async (query: any) => {
+        const results: any[] = []
+        for (const [id, entity] of mockIndex.entries()) {
+          let matches = true
+          for (const [key, value] of Object.entries(query)) {
+            if (key === 'type' && entity.type !== value) {
+              matches = false
+              break
+            }
+            if (entity.metadata?.[key] !== value) {
+              matches = false
+              break
+            }
+          }
+          if (matches) {
+            results.push({ id, ...entity })
+          }
+        }
+        return results
+      }),
+      commit: vi.fn(async () => 'commit-hash-123')
+    }
+
+    manager = new VersionManager(mockBrain)
+  })
+
+  describe('save()', () => {
+    it('should save a new version', async () => {
+      // Add test entity
+      mockIndex.set('user-123', {
+        id: 'user-123',
+        type: 'user',
+        name: 'Alice',
+        metadata: { email: 'alice@example.com' }
+      })
+
+      const version = await manager.save('user-123', {
+        tag: 'v1.0',
+        description: 'Initial version'
+      })
+
+      expect(version.version).toBe(1)
+      expect(version.entityId).toBe('user-123')
+      expect(version.branch).toBe('main')
+      expect(version.tag).toBe('v1.0')
+      expect(version.description).toBe('Initial version')
+      expect(version.contentHash).toBeDefined()
+      expect(version.commitHash).toBe('commit-hash-123')
+    })
+
+    it('should increment version numbers', async () => {
+      mockIndex.set('doc-1', {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Version 1' }
+      })
+
+      const v1 = await manager.save('doc-1', { tag: 'v1' })
+      expect(v1.version).toBe(1)
+
+      // Update entity
+      mockIndex.set('doc-1', {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Version 2' }
+      })
+
+      const v2 = await manager.save('doc-1', { tag: 'v2' })
+      expect(v2.version).toBe(2)
+
+      mockIndex.set('doc-1', {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Version 3' }
+      })
+
+      const v3 = await manager.save('doc-1', { tag: 'v3' })
+      expect(v3.version).toBe(3)
+    })
+
+    it('should deduplicate identical content', async () => {
+      mockIndex.set('note-1', {
+        id: 'note-1',
+        type: 'document',
+        name: 'Note',
+        metadata: { content: 'Unchanged' }
+      })
+
+      const v1 = await manager.save('note-1', { tag: 'v1' })
+      const v2 = await manager.save('note-1', { tag: 'v2' })
+
+      // Should return same version (content unchanged)
+      expect(v2.version).toBe(v1.version)
+      expect(v2.contentHash).toBe(v1.contentHash)
+    })
+
+    it('should throw if entity does not exist', async () => {
+      await expect(
+        manager.save('nonexistent', { tag: 'v1' })
+      ).rejects.toThrow('Entity nonexistent not found')
+    })
+
+    it('should save without tag or description', async () => {
+      mockIndex.set('test-1', {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      })
+
+      const version = await manager.save('test-1')
+      expect(version.version).toBe(1)
+      expect(version.tag).toBeUndefined()
+      expect(version.description).toBeUndefined()
+    })
+  })
+
+  describe('restore()', () => {
+    it('should restore entity to specific version', async () => {
+      // Save version 1
+      mockIndex.set('config-1', {
+        id: 'config-1',
+        type: 'thing',
+        name: 'Config',
+        metadata: { theme: 'light', version: 1 }
+      })
+      await manager.save('config-1', { tag: 'v1' })
+
+      // Update to version 2
+      mockIndex.set('config-1', {
+        id: 'config-1',
+        type: 'thing',
+        name: 'Config',
+        metadata: { theme: 'dark', version: 2 }
+      })
+      await manager.save('config-1', { tag: 'v2' })
+
+      // Restore to v1
+      await manager.restore('config-1', 1)
+
+      // Verify saveNounMetadata was called with v1 data
+      expect(mockBrain.saveNounMetadata).toHaveBeenCalledWith(
+        'config-1',
+        expect.objectContaining({
+          metadata: expect.objectContaining({ theme: 'light', version: 1 })
+        })
+      )
+    })
+
+    it('should restore by tag', async () => {
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { status: 'alpha' }
+      })
+      await manager.save('app-1', { tag: 'alpha' })
+
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { status: 'beta' }
+      })
+      await manager.save('app-1', { tag: 'beta' })
+
+      // Restore to alpha
+      await manager.restore('app-1', 'alpha')
+
+      expect(mockBrain.saveNounMetadata).toHaveBeenCalledWith(
+        'app-1',
+        expect.objectContaining({
+          metadata: expect.objectContaining({ status: 'alpha' })
+        })
+      )
+    })
+
+    it('should throw if version not found', async () => {
+      mockIndex.set('test-1', {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      })
+      await manager.save('test-1')
+
+      await expect(
+        manager.restore('test-1', 999)
+      ).rejects.toThrow('Version 999 not found')
+    })
+  })
+
+  describe('list()', () => {
+    it('should list all versions for entity', async () => {
+      mockIndex.set('log-1', {
+        id: 'log-1',
+        type: 'document',
+        name: 'Log',
+        metadata: { entry: 1 }
+      })
+
+      await manager.save('log-1', { tag: 'v1' })
+
+      mockIndex.set('log-1', {
+        id: 'log-1',
+        type: 'document',
+        name: 'Log',
+        metadata: { entry: 2 }
+      })
+      await manager.save('log-1', { tag: 'v2' })
+
+      mockIndex.set('log-1', {
+        id: 'log-1',
+        type: 'document',
+        name: 'Log',
+        metadata: { entry: 3 }
+      })
+      await manager.save('log-1', { tag: 'v3' })
+
+      const versions = await manager.list('log-1')
+      expect(versions).toHaveLength(3)
+      expect(versions[0].version).toBe(3) // Newest first
+      expect(versions[1].version).toBe(2)
+      expect(versions[2].version).toBe(1)
+    })
+
+    it('should filter by tag pattern', async () => {
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { v: 1 }
+      })
+
+      await manager.save('app-1', { tag: 'v1.0.0' })
+
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { v: 2 }
+      })
+      await manager.save('app-1', { tag: 'v1.1.0' })
+
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { v: 3 }
+      })
+      await manager.save('app-1', { tag: 'v2.0.0' })
+
+      const v1Versions = await manager.list('app-1', { tag: 'v1.*' })
+      expect(v1Versions).toHaveLength(2)
+      expect(v1Versions[0].tag).toBe('v1.1.0')
+      expect(v1Versions[1].tag).toBe('v1.0.0')
+    })
+
+    it('should limit results', async () => {
+      mockIndex.set('data-1', {
+        id: 'data-1',
+        type: 'thing',
+        name: 'Data',
+        metadata: { v: 1 }
+      })
+
+      for (let i = 1; i <= 5; i++) {
+        mockIndex.set('data-1', {
+          id: 'data-1',
+          type: 'thing',
+          name: 'Data',
+          metadata: { v: i }
+        })
+        await manager.save('data-1', { tag: `v${i}` })
+      }
+
+      const versions = await manager.list('data-1', { limit: 3 })
+      expect(versions).toHaveLength(3)
+      expect(versions[0].version).toBe(5)
+      expect(versions[1].version).toBe(4)
+      expect(versions[2].version).toBe(3)
+    })
+
+    it('should return empty array if no versions', async () => {
+      mockIndex.set('new-1', {
+        id: 'new-1',
+        type: 'thing',
+        name: 'New',
+        metadata: {}
+      })
+
+      const versions = await manager.list('new-1')
+      expect(versions).toHaveLength(0)
+    })
+  })
+
+  describe('compare()', () => {
+    it('should compare two versions', async () => {
+      mockIndex.set('user-1', {
+        id: 'user-1',
+        type: 'user',
+        name: 'Bob',
+        metadata: { email: 'bob@example.com', age: 30 }
+      })
+      await manager.save('user-1', { tag: 'v1' })
+
+      mockIndex.set('user-1', {
+        id: 'user-1',
+        type: 'user',
+        name: 'Robert',
+        metadata: { email: 'robert@example.com', age: 30, city: 'NYC' }
+      })
+      await manager.save('user-1', { tag: 'v2' })
+
+      const diff = await manager.compare('user-1', 1, 2)
+
+      expect(diff.totalChanges).toBeGreaterThan(0)
+      expect(diff.modified.length).toBeGreaterThan(0)
+      expect(diff.added.length).toBeGreaterThan(0)
+
+      const nameChange = diff.modified.find(c => c.path.includes('name'))
+      expect(nameChange?.oldValue).toBe('Bob')
+      expect(nameChange?.newValue).toBe('Robert')
+
+      const cityAdd = diff.added.find(c => c.path.includes('city'))
+      expect(cityAdd?.newValue).toBe('NYC')
+    })
+
+    it('should compare by tags', async () => {
+      mockIndex.set('doc-1', {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Alpha' }
+      })
+      await manager.save('doc-1', { tag: 'alpha' })
+
+      mockIndex.set('doc-1', {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Beta' }
+      })
+      await manager.save('doc-1', { tag: 'beta' })
+
+      const diff = await manager.compare('doc-1', 'alpha', 'beta')
+
+      expect(diff.modified.length).toBeGreaterThan(0)
+      const contentChange = diff.modified.find(c => c.path.includes('content'))
+      expect(contentChange?.oldValue).toBe('Alpha')
+      expect(contentChange?.newValue).toBe('Beta')
+    })
+
+    it('should detect identical versions', async () => {
+      mockIndex.set('same-1', {
+        id: 'same-1',
+        type: 'thing',
+        name: 'Same',
+        metadata: { value: 100 }
+      })
+      await manager.save('same-1', { tag: 'v1' })
+      await manager.save('same-1', { tag: 'v2' })  // Content unchanged
+
+      const diff = await manager.compare('same-1', 1, 1)
+      expect(diff.identical).toBe(true)
+      expect(diff.totalChanges).toBe(0)
+    })
+  })
+
+  describe('prune()', () => {
+    it('should prune old versions keeping recent', async () => {
+      mockIndex.set('log-1', {
+        id: 'log-1',
+        type: 'document',
+        name: 'Log',
+        metadata: { entry: 1 }
+      })
+
+      for (let i = 1; i <= 10; i++) {
+        mockIndex.set('log-1', {
+          id: 'log-1',
+          type: 'document',
+          name: 'Log',
+          metadata: { entry: i }
+        })
+        await manager.save('log-1', { tag: `v${i}` })
+      }
+
+      const result = await manager.prune('log-1', {
+        keepRecent: 5,
+        keepTagged: false
+      })
+
+      expect(result.deleted).toBe(5)
+      expect(result.kept).toBe(5)
+
+      const remaining = await manager.list('log-1')
+      expect(remaining).toHaveLength(5)
+      expect(remaining[0].version).toBe(10) // Most recent
+    })
+
+    it('should keep tagged versions', async () => {
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { v: 1 }
+      })
+
+      await manager.save('app-1', { tag: 'release' })
+
+      for (let i = 2; i <= 10; i++) {
+        mockIndex.set('app-1', {
+          id: 'app-1',
+          type: 'thing',
+          name: 'App',
+          metadata: { v: i }
+        })
+        await manager.save('app-1')  // No tag
+      }
+
+      const result = await manager.prune('app-1', {
+        keepRecent: 3,
+        keepTagged: true
+      })
+
+      const remaining = await manager.list('app-1')
+      const releaseVersion = remaining.find(v => v.tag === 'release')
+      expect(releaseVersion).toBeDefined()
+    })
+
+    it('should respect keepAfter timestamp', async () => {
+      mockIndex.set('data-1', {
+        id: 'data-1',
+        type: 'thing',
+        name: 'Data',
+        metadata: { v: 1 }
+      })
+
+      const now = Date.now()
+      const oneDayAgo = now - 24 * 60 * 60 * 1000
+
+      await manager.save('data-1', { tag: 'old' })
+
+      // Simulate newer versions
+      for (let i = 2; i <= 5; i++) {
+        mockIndex.set('data-1', {
+          id: 'data-1',
+          type: 'thing',
+          name: 'Data',
+          metadata: { v: i }
+        })
+        await manager.save('data-1', { tag: `new${i}` })
+      }
+
+      const result = await manager.prune('data-1', {
+        keepAfter: oneDayAgo,
+        keepTagged: false
+      })
+
+      expect(result.deleted).toBeGreaterThanOrEqual(0)
+    })
+  })
+
+  describe('getVersion()', () => {
+    it('should get specific version by number', async () => {
+      mockIndex.set('test-1', {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: { v: 1 }
+      })
+      const v1 = await manager.save('test-1', { tag: 'v1' })
+
+      mockIndex.set('test-1', {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: { v: 2 }
+      })
+      await manager.save('test-1', { tag: 'v2' })
+
+      const version = await manager.getVersion('test-1', 1)
+      expect(version).toBeDefined()
+      expect(version?.version).toBe(1)
+      expect(version?.tag).toBe('v1')
+    })
+
+    it('should return null if version not found', async () => {
+      mockIndex.set('test-1', {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      })
+      await manager.save('test-1')
+
+      const version = await manager.getVersion('test-1', 999)
+      expect(version).toBeNull()
+    })
+  })
+
+  describe('getVersionByTag()', () => {
+    it('should get version by tag', async () => {
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { status: 'alpha' }
+      })
+      await manager.save('app-1', { tag: 'alpha' })
+
+      mockIndex.set('app-1', {
+        id: 'app-1',
+        type: 'thing',
+        name: 'App',
+        metadata: { status: 'beta' }
+      })
+      await manager.save('app-1', { tag: 'beta' })
+
+      const betaVersion = await manager.getVersionByTag('app-1', 'beta')
+      expect(betaVersion).toBeDefined()
+      expect(betaVersion?.tag).toBe('beta')
+    })
+
+    it('should return null if tag not found', async () => {
+      mockIndex.set('test-1', {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      })
+      await manager.save('test-1', { tag: 'v1' })
+
+      const version = await manager.getVersionByTag('test-1', 'nonexistent')
+      expect(version).toBeNull()
+    })
+  })
+
+  describe('getVersionCount()', () => {
+    it('should count versions', async () => {
+      mockIndex.set('doc-1', {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { v: 1 }
+      })
+
+      expect(await manager.getVersionCount('doc-1')).toBe(0)
+
+      await manager.save('doc-1')
+      expect(await manager.getVersionCount('doc-1')).toBe(1)
+
+      mockIndex.set('doc-1', {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { v: 2 }
+      })
+      await manager.save('doc-1')
+      expect(await manager.getVersionCount('doc-1')).toBe(2)
+    })
+  })
+
+  describe('Branch Awareness', () => {
+    it('should track versions per branch', async () => {
+      mockIndex.set('branch-test', {
+        id: 'branch-test',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      })
+
+      // Save on main
+      mockBrain.currentBranch = 'main'
+      const mainV1 = await manager.save('branch-test', { tag: 'main-v1' })
+      expect(mainV1.branch).toBe('main')
+
+      // Save on feature
+      mockBrain.currentBranch = 'feature'
+      const featureV1 = await manager.save('branch-test', { tag: 'feature-v1' })
+      expect(featureV1.branch).toBe('feature')
+
+      // Versions should be independent
+      expect(mainV1.version).toBe(1)
+      expect(featureV1.version).toBe(1)  // Each branch starts at 1
+    })
+  })
+})

tests/unit/versioning/VersionStorage.test.ts

@@ -0,0 +1,548 @@
+/**
+ * VersionStorage Unit Tests (v5.3.0)
+ *
+ * Tests content-addressable storage:
+ * - SHA-256 content hashing
+ * - Content deduplication
+ * - Storage adapter integration
+ * - Save/load/delete operations
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { VersionStorage } from '../../../src/versioning/VersionStorage.js'
+import type { NounMetadata } from '../../../src/coreTypes.js'
+import type { EntityVersion } from '../../../src/versioning/VersionManager.js'
+
+describe('VersionStorage', () => {
+  let storage: VersionStorage
+  let mockBrain: any
+  let mockFiles: Map<string, string>
+
+  beforeEach(() => {
+    mockFiles = new Map()
+
+    mockBrain = {
+      storageAdapter: {
+        exists: vi.fn(async (path: string) => mockFiles.has(path)),
+        writeFile: vi.fn(async (path: string, data: string) => {
+          mockFiles.set(path, data)
+        }),
+        readFile: vi.fn(async (path: string) => {
+          const data = mockFiles.get(path)
+          if (!data) throw new Error('File not found')
+          return data
+        }),
+        deleteFile: vi.fn(async (path: string) => {
+          mockFiles.delete(path)
+        })
+      }
+    }
+
+    storage = new VersionStorage(mockBrain)
+  })
+
+  describe('hashEntity()', () => {
+    it('should generate consistent SHA-256 hashes', () => {
+      const entity: NounMetadata = {
+        id: 'user-123',
+        type: 'user',
+        name: 'Alice',
+        metadata: { email: 'alice@example.com' }
+      }
+
+      const hash1 = storage.hashEntity(entity)
+      const hash2 = storage.hashEntity(entity)
+
+      expect(hash1).toBe(hash2)
+      expect(hash1).toHaveLength(64)  // SHA-256 = 64 hex chars
+    })
+
+    it('should generate different hashes for different content', () => {
+      const entity1: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: {}
+      }
+
+      const entity2: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Bob',
+        metadata: {}
+      }
+
+      const hash1 = storage.hashEntity(entity1)
+      const hash2 = storage.hashEntity(entity2)
+
+      expect(hash1).not.toBe(hash2)
+    })
+
+    it('should ignore property order (stable JSON)', () => {
+      const entity1: NounMetadata = {
+        id: 'user-1',
+        type: 'user',
+        name: 'Alice',
+        metadata: { a: 1, b: 2, c: 3 }
+      }
+
+      const entity2: NounMetadata = {
+        type: 'user',
+        metadata: { c: 3, b: 2, a: 1 },
+        name: 'Alice',
+        id: 'user-1'
+      }
+
+      const hash1 = storage.hashEntity(entity1)
+      const hash2 = storage.hashEntity(entity2)
+
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should handle nested objects', () => {
+      const entity: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {
+          nested: {
+            deep: {
+              value: 'hello'
+            }
+          }
+        }
+      }
+
+      const hash = storage.hashEntity(entity)
+      expect(hash).toHaveLength(64)
+    })
+
+    it('should handle arrays', () => {
+      const entity: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {
+          tags: ['a', 'b', 'c']
+        }
+      }
+
+      const hash = storage.hashEntity(entity)
+      expect(hash).toHaveLength(64)
+    })
+
+    it('should handle null and undefined', () => {
+      const entity1: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: { value: null }
+      }
+
+      const entity2: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: { value: undefined }
+      }
+
+      const hash1 = storage.hashEntity(entity1)
+      const hash2 = storage.hashEntity(entity2)
+
+      expect(hash1).not.toBe(hash2)
+    })
+  })
+
+  describe('saveVersion()', () => {
+    it('should save version content to storage', async () => {
+      const entity: NounMetadata = {
+        id: 'user-123',
+        type: 'user',
+        name: 'Alice',
+        metadata: { email: 'alice@example.com' }
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'user-123',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      await storage.saveVersion(version, entity)
+
+      const expectedPath = `versions/entities/user-123/${version.contentHash}.json`
+      expect(mockFiles.has(expectedPath)).toBe(true)
+
+      const savedData = mockFiles.get(expectedPath)
+      expect(savedData).toBeDefined()
+      expect(JSON.parse(savedData!)).toEqual(entity)
+    })
+
+    it('should deduplicate identical content', async () => {
+      const entity: NounMetadata = {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Same content' }
+      }
+
+      const contentHash = storage.hashEntity(entity)
+
+      const version1: EntityVersion = {
+        version: 1,
+        entityId: 'doc-1',
+        branch: 'main',
+        commitHash: 'commit-1',
+        timestamp: Date.now(),
+        contentHash
+      }
+
+      const version2: EntityVersion = {
+        version: 2,
+        entityId: 'doc-1',
+        branch: 'main',
+        commitHash: 'commit-2',
+        timestamp: Date.now() + 1000,
+        contentHash  // Same hash!
+      }
+
+      await storage.saveVersion(version1, entity)
+      const writeCallCount1 = mockBrain.storageAdapter.writeFile.mock.calls.length
+
+      await storage.saveVersion(version2, entity)
+      const writeCallCount2 = mockBrain.storageAdapter.writeFile.mock.calls.length
+
+      // Should not write again (deduplication)
+      expect(writeCallCount2).toBe(writeCallCount1)
+    })
+
+    it('should store different content separately', async () => {
+      const entity1: NounMetadata = {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Version 1' }
+      }
+
+      const entity2: NounMetadata = {
+        id: 'doc-1',
+        type: 'document',
+        name: 'Doc',
+        metadata: { content: 'Version 2' }
+      }
+
+      const version1: EntityVersion = {
+        version: 1,
+        entityId: 'doc-1',
+        branch: 'main',
+        commitHash: 'commit-1',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity1)
+      }
+
+      const version2: EntityVersion = {
+        version: 2,
+        entityId: 'doc-1',
+        branch: 'main',
+        commitHash: 'commit-2',
+        timestamp: Date.now() + 1000,
+        contentHash: storage.hashEntity(entity2)
+      }
+
+      await storage.saveVersion(version1, entity1)
+      await storage.saveVersion(version2, entity2)
+
+      const path1 = `versions/entities/doc-1/${version1.contentHash}.json`
+      const path2 = `versions/entities/doc-1/${version2.contentHash}.json`
+
+      expect(mockFiles.has(path1)).toBe(true)
+      expect(mockFiles.has(path2)).toBe(true)
+      expect(path1).not.toBe(path2)
+    })
+  })
+
+  describe('loadVersion()', () => {
+    it('should load version content from storage', async () => {
+      const entity: NounMetadata = {
+        id: 'user-123',
+        type: 'user',
+        name: 'Alice',
+        metadata: { email: 'alice@example.com' }
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'user-123',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      // Save first
+      await storage.saveVersion(version, entity)
+
+      // Load
+      const loaded = await storage.loadVersion(version)
+
+      expect(loaded).toEqual(entity)
+    })
+
+    it('should return null if version not found', async () => {
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'nonexistent',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: 'fake-hash'
+      }
+
+      const loaded = await storage.loadVersion(version)
+      expect(loaded).toBeNull()
+    })
+
+    it('should handle complex nested data', async () => {
+      const entity: NounMetadata = {
+        id: 'complex-1',
+        type: 'thing',
+        name: 'Complex',
+        metadata: {
+          nested: {
+            array: [1, 2, 3],
+            object: { key: 'value' }
+          },
+          tags: ['a', 'b', 'c']
+        }
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'complex-1',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      await storage.saveVersion(version, entity)
+      const loaded = await storage.loadVersion(version)
+
+      expect(loaded).toEqual(entity)
+    })
+  })
+
+  describe('deleteVersion()', () => {
+    it('should delete version from storage', async () => {
+      const entity: NounMetadata = {
+        id: 'user-123',
+        type: 'user',
+        name: 'Alice',
+        metadata: {}
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'user-123',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      // Save
+      await storage.saveVersion(version, entity)
+      const path = `versions/entities/user-123/${version.contentHash}.json`
+      expect(mockFiles.has(path)).toBe(true)
+
+      // Delete
+      await storage.deleteVersion(version)
+      expect(mockFiles.has(path)).toBe(false)
+    })
+
+    it('should handle deleting non-existent version gracefully', async () => {
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'nonexistent',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: 'fake-hash'
+      }
+
+      // Should not throw
+      await storage.deleteVersion(version)
+    })
+  })
+
+  describe('Storage Adapter Integration', () => {
+    it('should work with memory storage adapter', async () => {
+      const entity: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: { value: 123 }
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'test-1',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      await storage.saveVersion(version, entity)
+      const loaded = await storage.loadVersion(version)
+
+      expect(loaded).toEqual(entity)
+    })
+
+    it('should use adapter.set if writeFile unavailable', async () => {
+      // Mock adapter with set/get instead of writeFile/readFile
+      mockBrain.storageAdapter = {
+        exists: vi.fn(async () => false),
+        set: vi.fn(async (path: string, data: string) => {
+          mockFiles.set(path, data)
+        }),
+        get: vi.fn(async (path: string) => {
+          const data = mockFiles.get(path)
+          if (!data) throw new Error('Not found')
+          return data
+        }),
+        delete: vi.fn(async (path: string) => {
+          mockFiles.delete(path)
+        })
+      }
+
+      storage = new VersionStorage(mockBrain)
+
+      const entity: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'test-1',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      await storage.saveVersion(version, entity)
+      expect(mockBrain.storageAdapter.set).toHaveBeenCalled()
+
+      const loaded = await storage.loadVersion(version)
+      expect(mockBrain.storageAdapter.get).toHaveBeenCalled()
+      expect(loaded).toEqual(entity)
+    })
+
+    it('should throw if storage adapter missing', async () => {
+      mockBrain.storageAdapter = null
+      storage = new VersionStorage(mockBrain)
+
+      const entity: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'test-1',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      await expect(
+        storage.saveVersion(version, entity)
+      ).rejects.toThrow('Storage adapter not available')
+    })
+
+    it('should throw if adapter does not support required operations', async () => {
+      mockBrain.storageAdapter = {}  // No methods
+      storage = new VersionStorage(mockBrain)
+
+      const entity: NounMetadata = {
+        id: 'test-1',
+        type: 'thing',
+        name: 'Test',
+        metadata: {}
+      }
+
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'test-1',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash: storage.hashEntity(entity)
+      }
+
+      await expect(
+        storage.saveVersion(version, entity)
+      ).rejects.toThrow('does not support write operations')
+    })
+  })
+
+  describe('Path Generation', () => {
+    it('should generate correct storage paths', async () => {
+      const entity: NounMetadata = {
+        id: 'user-123',
+        type: 'user',
+        name: 'Alice',
+        metadata: {}
+      }
+
+      const contentHash = storage.hashEntity(entity)
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'user-123',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash
+      }
+
+      await storage.saveVersion(version, entity)
+
+      const expectedPath = `versions/entities/user-123/${contentHash}.json`
+      expect(mockFiles.has(expectedPath)).toBe(true)
+    })
+
+    it('should handle entity IDs with special characters', async () => {
+      const entity: NounMetadata = {
+        id: 'user:123:profile',
+        type: 'user',
+        name: 'Alice',
+        metadata: {}
+      }
+
+      const contentHash = storage.hashEntity(entity)
+      const version: EntityVersion = {
+        version: 1,
+        entityId: 'user:123:profile',
+        branch: 'main',
+        commitHash: 'commit-123',
+        timestamp: Date.now(),
+        contentHash
+      }
+
+      await storage.saveVersion(version, entity)
+
+      const expectedPath = `versions/entities/user:123:profile/${contentHash}.json`
+      expect(mockFiles.has(expectedPath)).toBe(true)
+    })
+  })
+})