Markdown vs Engrams: Choosing the Right Approach

Markdown files and the AGENTS.md pattern are excellent for small projects. But as your codebase grows, so does the challenge of keeping knowledge organized, searchable, and relevant. This guide explains when each approach shines — and how to use them together.

The Strengths of Markdown

Markdown files have real advantages, especially for small teams and early-stage projects:

  • Version control friendly. Markdown lives in Git, so every change is tracked and reviewable.
  • Human-readable. No special tools needed — open any text editor and read or edit.
  • Low friction. Create a file, write some notes, commit. No setup required.
  • Portable. Copy files anywhere. No database to migrate or export.
  • Familiar. Most developers already know Markdown and Git workflows.
  • Searchable in code editors. Use Ctrl+Shift+F (or Cmd+Shift+F) to find text across files.

Where Markdown Breaks Down

As projects scale, markdown-based approaches hit real limits:

1. Search becomes painful

With 50+ decision documents, finding the right one requires:

  • Remembering the exact filename or keywords used
  • Manually searching through multiple files
  • Scrolling through long documents to find the relevant section
  • No way to find related decisions unless you manually link them

Example: You're building a caching layer and want to know if the team has already decided on Redis vs Memcached. You search for "cache" and get 20 results across different files. Some are about HTTP caching, others about database query caching. You have to read each one.

2. Semantic understanding is impossible

Markdown search is keyword-based only. It can't understand meaning:

  • A decision about "query performance optimization" won't show up when you search for "caching strategy"
  • Related concepts are scattered across files with no automatic connections
  • You can't ask "what patterns help with scalability?" — you have to manually browse

3. Knowledge graph is manual and fragile

Linking decisions together requires:

  • Manually maintaining cross-references in markdown files
  • Broken links when files are renamed or moved
  • No way to visualize how decisions connect
  • Relationships are one-directional (you have to update both files)

4. Context selection is all-or-nothing

When you ask your AI for help, you either:

  • Manually copy-paste relevant markdown files into the chat (tedious, error-prone)
  • Let the AI see nothing (and get generic, context-free answers)
  • Paste everything (slow, expensive, noisy)

There's no smart way to say "give me the 3-5 most relevant decisions for this task."

5. Governance and consistency are hard to enforce

With markdown files:

  • No standard format — each file might look different
  • No way to track who made decisions or when
  • Conflicting decisions can exist in different files with no warning
  • No audit trail for compliance or team alignment

6. Scaling creates information overload

As your project grows:

  • 100+ markdown files become hard to navigate
  • Onboarding new team members means "read all these files"
  • Keeping documentation up-to-date becomes a chore
  • Old decisions pile up and become noise

How Engrams Solves These Problems

Semantic search that understands meaning

Engrams uses vector embeddings to understand the meaning of your decisions, not just keywords:

  • Search for "caching strategy" and find decisions about Redis, Memcached, and HTTP caching
  • Ask "what patterns help with scalability?" and get relevant architectural decisions
  • Find related items even when they use completely different words

Automatic knowledge graph

Engrams lets you explicitly link decisions, patterns, and tasks:

  • Connect a design decision to the coding patterns that implement it
  • Link a task to the decisions it depends on
  • Visualize how your project knowledge connects
  • Your AI can follow these connections to understand the bigger picture

Smart context selection

When your AI asks Engrams for context, it gets exactly what it needs:

  • Engrams ranks items by relevance to the current task
  • Only the most useful items are included (fast, affordable)
  • Your AI stays focused and informed
  • See Context Budgeting for details

Structured, consistent knowledge

Engrams enforces structure without being rigid:

  • Decisions have consistent fields: summary, rationale, tags, timestamps
  • Patterns, tasks, and custom data follow predictable formats
  • Audit trails show who made decisions and when
  • Conflict detection warns when decisions contradict each other

Governance and team alignment

Engrams includes tools for teams:

  • Scope decisions to specific teams or projects
  • Detect conflicts between decisions
  • Track decision ownership and approval status
  • See Team Governance for details

Onboarding and knowledge discovery

New team members can quickly understand your project:

  • Engrams provides a structured briefing of key decisions and patterns
  • The knowledge dashboard visualizes your project's architecture
  • Semantic search helps explore related concepts
  • See Project Onboarding for details

The Hybrid Approach: Markdown + Engrams

You don't have to choose. The best approach combines both:

Use markdown for:

  • README files — Quick start guides, setup instructions
  • Architecture diagrams — Visual overviews in code comments
  • API documentation — Endpoint specs, request/response examples
  • Runbooks — Step-by-step deployment or troubleshooting guides
  • Code comments — Inline explanations of complex logic

Use Engrams for:

  • Design decisions — Why you chose a particular approach
  • Architectural patterns — Reusable solutions to common problems
  • Project progress — Tasks, milestones, and status tracking
  • Team knowledge — Decisions that affect multiple people or projects
  • Context for AI — Information your AI assistant needs to write good code

How they work together:

  1. Markdown is the source of truth for implementation details. Your README explains how to run the project. Your code comments explain why a function works a certain way.
  2. Engrams is the source of truth for decisions and context. When you decide to use PostgreSQL instead of MongoDB, you log that decision in Engrams. When you establish a pattern for error handling, you save it as a system pattern.
  3. Your AI uses both. It reads your README to understand the project structure. It queries Engrams to understand the decisions and patterns that should guide its work.
  4. Engrams can link to markdown files. A decision in Engrams can reference a specific markdown file or section. A pattern can link to code examples in your repository.

Decision Criteria: When to Use Each

Scenario Markdown Engrams Both
Project size 1-5 people, <10 major decisions 5+ people, 10+ decisions Growing teams
Knowledge discovery Manual search, browsing Semantic search, knowledge graph Markdown for reference, Engrams for discovery
AI context Manual copy-paste Automatic, smart selection Engrams feeds AI, markdown for details
Governance Informal, Git-based Structured, auditable Engrams for decisions, markdown for processes
Onboarding "Read these 20 files" Structured briefing, guided discovery Engrams briefing, markdown for details
Relationships Manual links, fragile Automatic, queryable Engrams for connections, markdown for context
Version control Full history in Git Database history, export to Git Engrams + Git export for compliance

Getting Started with Engrams

If you're currently using markdown and want to add Engrams:

  1. Start small. Log your most important decisions and patterns first. You don't need to migrate everything at once.
  2. Keep markdown as-is. Your README, API docs, and code comments stay in Git. Engrams complements them, doesn't replace them.
  3. Use Engrams for AI context. When you ask your AI for help, it automatically gets the relevant decisions and patterns from Engrams.
  4. Build the knowledge graph gradually. As you log decisions, link related items. Over time, your knowledge becomes more connected and discoverable.
  5. Export to markdown when needed. Engrams can export your decisions and patterns to markdown files for sharing, archiving, or version control.

See Getting Started and Quick Start for installation and setup instructions.

Summary

Markdown is great for: Small projects, implementation details, version control, portability.

Engrams is great for: Scaling knowledge, semantic search, AI context, team governance, knowledge discovery.

Together they're powerful: Markdown for what humans read, Engrams for what AI needs to understand.