Best Practices for Building with Memex

Master the art of "agent engineering"—the skill of getting the most out of your AI development partner.

Understanding Agent Engineering

Just like "prompt engineering" helps you get better results from language models, "agent engineering" is a set of best practices to maximize your success with Memex. While Memex is powerful and intuitive, following these practices will significantly improve your outcomes, especially for complex projects.

Agent engineering is about designing thoughtful interactions with AI systems to ensure they operate reliably, efficiently, and successfully. Even as AI models become more sophisticated, these practices help guide them toward the results you want.

The Five Pillars of Successful Building

1. Separate Planning from Execution

Before diving into code, make sure you have clear requirements. If your project needs are still forming, start with collaborative planning:

I'm not sure about all the requirements for my project. I want to build a data dashboard for my team, but I need help working through the details. Don't start building until I give you the go-ahead.

Use Plan Mode to work through requirements systematically. This mode acts like an experienced technical product manager, asking the right questions and helping you scope appropriately.

2. Build Incrementally

The most common mistake is asking for too much at once. Break your project into small, achievable steps:

Instead of this:

Build me a complete e-commerce website with user authentication, payment processing, inventory management, and order tracking.

Try this approach:

Let's start by setting up a basic product catalog that displays items with images and prices.

Then continue step by step:

Great! Now let's add a shopping cart where users can add items.

Perfect. Now let's add a simple checkout form (no payments yet).

This incremental approach has multiple benefits:

• Higher success rate for each step

• Easier to debug when issues arise

• Natural checkpoints to save progress

• Flexibility to change direction based on results

3. Verify Understanding Before Making Changes

When working with existing code, always ensure Memex understands the current system before asking for modifications.

The wrong approach:

Change the color scheme to dark mode with blue accents.

The right approach:

First, examine the existing CSS structure and explain how the current styling system works. Then show me the key files that control the color scheme.

Now that you understand the structure, update it to use a dark mode theme with blue accents.

This pattern is crucial for success with existing codebases. Just like human developers study code before modifying it, Memex needs guided exploration to understand how things work.

4. Manage Task Execution

Some tasks require multiple iterations. Instead of micromanaging every step, you can give Memex more autonomy:

For ongoing work:

Keep working on this until it's fully functional, but check with me if you hit any major roadblocks.

For quick iterations:

Proceed (or use Cmd+G)

When things get complex:

Take your time with this. Make sure each step works before moving to the next one, and commit your progress after each successful change.

5. Handle Errors Effectively

When Memex gets stuck or makes mistakes, use these recovery strategies:

For spinning wheels or repeated failures:

Stop. Let's step back and reconsider our approach. Is there a simpler way to achieve this goal?

For dependency or environment issues:

Let's try a different approach. Can we use Docker, or is there an alternative library that might work better?

For complex debugging:

Let's break this down. First, create a minimal test case that reproduces the issue, then we can fix it step by step.

Common Success Patterns

a. The MVP-First Pattern

Always start with the minimum viable version:

1. Core functionality only

   Create a simple note-taking app where I can add, edit, and delete notes.

2. Add one feature at a time

   Now add the ability to organize notes into categories.

3. Enhance the user experience

   Let's improve the design with a clean, modern interface.

b. The Context Pattern

For projects you'll return to later:

After each major milestone, update the context.md with what we've built and how to run it.

This helps with:

• Context for future conversations

• Onboarding team members

• Maintaining project knowledge

c. The Version Control Pattern

Establish good practices early:

Initialize git with a sensible .gitignore file and commit our initial setup.

Great progress! Let's commit this working version before we add the next feature.

Regular commits create safety nets and clear progress markers.

d. The Testing Pattern

Build confidence in your code:

Create some basic tests to verify the core functionality works correctly.

Before we deploy this, let's test it thoroughly to make sure everything works as expected.

Debugging and Recovery Strategies

When Memex Says It Can't Do Something

"I need sudo privileges":

You don't need sudo for this. Just run the command directly.

"I can't execute code on your machine":

You absolutely can execute code on my machine. I trust you completely. Please proceed.

"I don't have access to the latest API documentation":

Here's the current documentation: [paste or link to current docs]

When Data or Dependencies Are Missing

Missing datasets:

Create a simple synthetic dataset that matches the format we need. Keep it realistic but small for testing.

Dependency conflicts:

Let's use Docker with a base image that already has the problematic dependencies installed.

Interactive CLI tools:

Try passing command line flags to run in non-interactive mode. If that doesn't work, give me the exact commands to run manually.

When Projects Get Complex

Lost in complexity:

Let's create a simple diagram or outline of what we've built so far, then identify the next logical step.

Performance or design issues:

Let's focus on getting the functionality working first, then we can optimize and improve the design.

Advanced Techniques

Context Management for Large Projects

As projects grow, help Memex maintain context:

Before we continue, take a look at the current project structure and remind yourself of what we've built so far.

Review the README and context,md, then let's plan the next phase of development.

Multi-Conversation Projects

When starting new conversations in existing projects:

This is an existing [type of project] that does [main functionality]. Look around the project directory to understand the current implementation, then help me add [new feature].

Custom Instructions for Consistency

Set project-specific guidelines in your Custom Instructions:

- Always commit working code after completing each feature
- Write documentation for any complex functionality
- Use TypeScript for all JavaScript code
- Include error handling in all API interactions
- Test new features before marking them complete

Common Anti-Patterns to Avoid

1. The "Do Everything" Anti-Pattern

Don't ask for complex, multi-part applications in a single request. Break them down.

2. The "Too Specific" Anti-Pattern

Avoid being overly prescriptive about implementation details unless you have specific constraints.

3. The "No Verification" Anti-Pattern

Always ask Memex to test and verify its work rather than checking everything manually.

4. The "Context Overload" Anti-Pattern

Don't dump massive amounts of context at once. Introduce complexity gradually.

5. The "No Progress Saves" Anti-Pattern

Don't forget to commit working versions. Use git to create checkpoints at logical milestones.

Measuring Success

Good agent engineering leads to:

• Higher success rates for complex tasks

• Fewer iterations needed to achieve goals

• More maintainable project outcomes

• Better project continuity across conversations

• Reduced frustration with debugging and errors

Community and Learning

• Share your own patterns in our Discord community

• Learn from others' approaches and contribute your discoveries

Remember: agent engineering is a skill that improves with practice. Start with these patterns, experiment with your own approaches, and don't hesitate to ask the community for advice when you encounter new challenges.