isar_agent_memory - Dart RAG Development

Development skill for contributing to `isar_agent_memory`, a Dart/Flutter package providing advanced RAG (Retrieval-Augmented Generation) capabilities with local-first storage.

Project Context

**Language**: Dart (`>=3.2.0 <4.0.0`)

**Database**: ObjectBox for vector storage (HNSW index)

**Package Type**: pub.dev package for Flutter/Dart projects

**Repository**: iberi22/isar_agent_memory

This is a reusable, open-source cognitive agent memory system inspired by Cognee and Graphiti. Features graph-based nodes, semantic embeddings, and memory degree management.

Project Structure

```

lib/

├── isar_agent_memory.dart # Main export file

└── src/

├── memory_graph.dart # Core graph-based memory

├── vector_index*.dart # Vector search implementations

├── embeddings_*.dart # Embedding adapters

└── ... # Advanced features

test/ # Unit and integration tests

tool/ # Release automation scripts

example/ # Usage examples

```

Development Workflow

1. Understand Dart Coding Standards

Follow these conventions strictly:

2. Import Organization

Organize imports in three groups (separated by blank lines), sorted alphabetically within each:

1. Dart SDK imports (`dart:*`)

2. Package imports (`package:*`)

3. Relative imports (internal files)

**Example:**

```dart

import 'dart:async';

import 'dart:convert';

import 'package:objectbox/objectbox.dart';

import 'package:uuid/uuid.dart';

import 'memory_graph.dart';

import 'vector_index.dart';

```

3. Error Handling Best Practices

**Example:**

```dart

final box = store.box<MemoryNode>();

final query = box.query(condition).build();

try {

final results = query.find();

return results;

} finally {

query.close();

}

```

4. Core Dependencies

Familiarize yourself with these key dependencies:

Build and Test Commands

```bash

Install dependencies

dart pub get

Analyze code (MUST pass before committing)

dart analyze

Format code

dart format .

Run all tests

dart test

Run specific test file

dart test test/smoke_test.dart

Verify package is ready for publish

dart pub publish --dry-run

```

Adding New Features

Follow this pattern when adding features:

1. **Implement** - Create implementation in `lib/src/`

2. **Export** - Add export to `lib/isar_agent_memory.dart`

3. **Test** - Add comprehensive tests in `test/`

4. **Document** - Update relevant `.md` documentation files

5. **Changelog** - Add entry to `CHANGELOG.md`

Critical Release Process

**⚠️ ALWAYS follow this process for version changes:**

Step 1: Update Version

Use the automated script to ensure consistency across all files:

```powershell

.\tool\update_version.ps1 -NewVersion "X.Y.Z"

```

This updates:

Step 2: Update CHANGELOG.md

Add a new section at the top:

```markdown

[X.Y.Z] - YYYY-MM-DD

Added

Changed

Fixed

```

Step 3: Commit with Conventional Commits

Use these commit message prefixes:

Step 4: Automated Release Flow

After pushing to `main`:

1. **version-sync.yml** - Validates version consistency across files

2. **release-on-merge.yml** - Creates git tag and GitHub Release

3. **publish-to-pub-dev.yml** - Publishes stable releases to pub.dev automatically

**Note:** Prereleases (`beta`, `alpha`, `rc`) are NOT automatically published to pub.dev.

CI/CD Workflows

| Workflow | Trigger | Purpose |

|----------|---------|---------|

| `ci.yml` | PR/Push | Lint, analyze, test |

| `version-sync.yml` | PR/Push | Validate version consistency |

| `release-on-merge.yml` | Push to main | Create tags and GitHub releases |

| `publish-to-pub-dev.yml` | Release published | Publish to pub.dev |

Common Troubleshooting

Compilation Errors

ObjectBox Query Pattern

Always close queries to prevent resource leaks:

```dart

final box = store.box<MemoryNode>();

final query = box.query(condition).build();

try {

final results = query.find();

return results;

} finally {

query.close();

}

```

Documentation Reference

Do NOT

Constraints