Architecture Memo for FDE Portfolio: Template & Example

Every FDE portfolio guide tells you to write an architecture memo for your FDE portfolio, but none of them actually show you what one looks like. You're told to document trade-offs, justify your decisions, and prove you think in systems. Then the advice stops. No template. No example. No way to know if what you wrote would survive an actual reviewer's read.

That's the gap this guide closes. You'll get a fill-in-the-blank template with section-by-section prompts, then a complete worked example for an agent memory system built on GigaRAG as the RAG pipeline. You'll see what reviewers actually look for, how to write the thing in a weekend, and what an architecture memo honestly cannot demonstrate no matter how well you write it.

In This Guide

• What FDE Reviewers Actually Look for in an Architecture Memo
• Architecture Memo vs. Architecture Decision Record (ADR)
• The Architecture Memo Template: Section by Section
• Architecture Memo For FDE Portfolio: A Step-by-Step Guide
• Worked Example: Architecture Memo for an Agent Memory System with GigaRAG
• Common Mistakes When Writing an Architecture Memo for FDE Portfolio
• How to Present the Architecture Memo in Your Portfolio
• What an Architecture Memo Cannot Demonstrate
• How to Write the Architecture Memo This Weekend
• Final Thoughts on Architecture Memos for FDE Portfolios

What FDE Reviewers Actually Look for in an Architecture Memo

FDE reviewers read architecture memos to answer one question: can this person make and defend a technical decision under real constraints? They're not checking whether you used the right framework or named the right database. They're checking whether you can explain why you chose what you chose, what you rejected, and what breaks when things go wrong.

The memo is a proxy for a conversation they can't have with you yet. A reviewer at a company hiring FDEs will spend five to ten minutes on your memo before deciding whether to read further. That's the window. Everything below is about using it well.

Decision rationale over code volume

Reviewers don't care how many lines you wrote. They care whether you can articulate why a particular architecture made sense for a particular problem. A memo that says "I used a vector database" without explaining the retrieval latency requirement that drove that choice tells the reviewer nothing about your judgment.

The strongest memos read like a trail of decisions. Each section answers a question the previous section raised. You chose X because of constraint Y, and you measured it against alternative Z. That's the signal.

Trade-off analysis as the core signal

Every architecture decision is a trade. Reviewers know this. What they're looking for is whether you know it too.

A memo that presents a design as obviously correct, with no mention of what it costs, reads as naive. A memo that says "I chose GigaRAG over a custom pipeline because it cut ingestion time from two days to four hours, but it means I lose fine-grained control over the chunking strategy" reads as experienced. The second sentence is the one that gets you the interview.

Name the trade. Name what you gave up. Name why it was worth it for this system, at this stage.

Evidence of production thinking

Production thinking means you considered what happens after the happy path. What happens when the context window overflows? What happens when the embedding model gets deprecated? What happens when retrieval returns nothing useful and the agent has to respond anyway?

Reviewers look for failure modes and mitigations. Not because they expect you to have solved every edge case, but because they want to see that you know edge cases exist. A memo that only describes the system working is a memo about a system that doesn't exist.

Clarity of communication under constraints

FDEs write for customers, for internal teams, for executives who will never read the code. The architecture memo is evidence you can do that.

This means short sentences where short sentences work. It means defining terms the first time you use them. It means a diagram description that someone can follow without seeing the diagram. It means cutting the paragraph that explains something twice.

The constraint is the reader's attention. Respect it.

[!note] An architecture memo is not a substitute for working code or a demo; reviewers expect to see the system in action alongside the document. The memo explains your reasoning, but the code proves you can execute.

Architecture Memo vs. Architecture Decision Record (ADR)

The Architecture Memo Template: Section by Section

Copy this structure. Fill in each section with your own system's specifics. The prompts under each heading tell you what to write, not how to write it. Keep the whole memo between 1,200 and 2,000 words. Longer than that and you're writing a design doc, not a memo.

Problem statement and context

Start with the problem, not the solution. One paragraph. What does the system need to do, and why does it matter? Name the user or the workflow. If you built an agent memory system, the problem is that agents forget everything between sessions and re-derive context from scratch every time. State the cost of not solving it: latency, token spend, wrong answers.

Don't describe your architecture here. That comes later. This section exists so the reviewer knows what you were optimizing for before they see what you built.

Requirements and constraints

List the hard requirements as bullets. Latency budget, retrieval quality threshold, scale, cost ceiling, compliance constraints. Each requirement gets a number where you have one: "p95 retrieval under 200ms" not "fast retrieval."

Then list the constraints you didn't choose. Team size, timeline, existing infrastructure, budget. Reviewers want to see that you designed within real limits, not in a vacuum.

System overview diagram description

Describe the system in prose as if the diagram doesn't exist. Start at the entry point and walk through the data flow. "A query enters through the API layer, gets embedded, and hits the vector store. The top-k results pass through a reranker before reaching the agent."

Keep it to one paragraph. The point is to give the reviewer a mental model they can hold while reading the deep-dive. If they can't follow this paragraph, they won't follow the rest.

Component deep-dive

Pick the three or four components that carry the most architectural weight. For an agent memory system, that's ingestion, embedding, retrieval, and memory consolidation. For each one, write two to three sentences: what it does, what it depends on, and the one decision that mattered most.

Don't describe every component. The reviewer doesn't need to know about your logging utility. They need to know where the hard problems were and how you solved them.

Trade-offs and rejected approaches

This is the section reviewers read most carefully. For each major decision, name the alternative you considered and why you rejected it. Be specific: "I considered LangChain's memory module but rejected it because it couples memory to the framework and made it hard to swap the retrieval backend."

Include at least two rejected approaches. Three is better. Each rejection should name a real cost of the alternative, not a strawman. If you can't think of a good reason someone would choose the alternative, you haven't understood the trade.

Failure modes and mitigations

List the ways the system breaks. Not hypothetical edge cases, the ones you actually hit or know are coming. Context window overflow. Stale memory entries. Retrieval returning nothing useful. Embedding model deprecation.

For each failure mode, one sentence on what happens and one sentence on what you did or would do. "When retrieval returns nothing above the similarity threshold, the agent falls back to a canned response and logs the query for review." That's enough.

Metrics and evaluation plan

Name the metrics you track and how you'd evaluate the system's quality. Retrieval precision, memory hit rate, latency p95, token cost per query. If you haven't measured these yet, say what you'd measure and how.

A reviewer will ask about evaluation. Having a plan, even an unimplemented one, is better than having nothing. It shows you know what "working" means.

Future work and open questions

Close with what you'd do next if you had more time. Two or three items, each with a reason. "I'd add memory consolidation to merge related entries and reduce retrieval noise, because the current system treats every memory as independent."

This section signals that you know the system is not finished. That's a feature, not a bug. Reviewers trust an engineer who knows what they haven't solved.

[!tip] For FDE roles, explicitly call out how your architecture handles real-world deployment constraints like intermittent connectivity, data privacy, or limited on-site compute—these are what distinguish forward deployed engineers from pure software engineers.

Architecture Memo For FDE Portfolio: A Step-by-Step Guide

1. Start with a one-paragraph context: the problem, constraints, and who the system serves.
2. State the core architectural decision in a single sentence (e.g., 'We chose a vector-backed memory store with a RAG pipeline for retrieval').
3. List at least two alternatives you seriously considered and why you rejected them.
4. Document the trade-offs of your chosen approach: what you gain, what you give up, and under what conditions you would revisit.
5. Describe the consequences: how the decision affects operations, scaling, and future changes.
6. Add a simple diagram (boxes and arrows) showing components and data flow.
7. Close with open questions or next steps to show ongoing architectural judgment.

Worked Example: Architecture Memo for an Agent Memory System with GigaRAG

Here's a complete memo for a customer support agent that needs persistent memory across sessions. It's condensed from a full 1,800-word version. Use it as a reference for tone, depth, and what "specific" looks like.

Problem statement: persistent agent memory across sessions

A support agent answers customer questions about a SaaS product. Without memory, every session starts cold. The agent re-asks for account details the customer already provided, re-derives context from scratch, and burns tokens re-reading the same documentation. The cost: p95 first-response latency of 4.2 seconds and a 23% rate of repeated questions. The fix is a memory layer that persists what the agent learns and retrieves it fast enough to not slow the conversation.

Requirements: latency, retrieval quality, scalability

• p95 retrieval under 180ms, including embedding and vector search
• Memory hit rate above 70% for repeat customer questions
• Retrieval precision above 0.85 on a 200-query eval set
• Support 10,000 concurrent sessions without degrading latency
• Token cost per query under $0.02 including memory retrieval

Constraints I didn't choose: a two-person team, a six-week timeline, and an existing Postgres instance I couldn't replace.

System overview: GigaRAG pipeline with vector store

A customer message enters through the API layer. The message gets embedded and searched against the vector store for relevant memories. The top-k memories pass through a reranker, then join the conversation history in the agent's context window. The agent responds. After the session, a consolidation job merges new memories into the store and prunes stale ones. GigaRAG handles the retrieval pipeline: embedding, vector search, and reranking as one call.

Component deep-dive: ingestion, embedding, retrieval, memory consolidation

Ingestion. Every resolved conversation produces a memory entry: the customer's question, the agent's answer, and the account context. Entries under 50 tokens get merged with existing ones to avoid fragmenting the store.

Embedding. I used GigaRAG's default embedding model. The decision that mattered: embedding the question and answer together, not separately. Separate embeddings doubled retrieval misses because the question alone didn't capture the answer's context.

Retrieval. GigaRAG returns top-10 candidates with similarity scores. A threshold of 0.72 filters out noise. Below that, the agent falls back to the documentation index.

Memory consolidation. A nightly job merges entries that reference the same account and topic, and expires entries untouched for 30 days. Without this, the store grew 18% weekly and retrieval precision dropped.

Trade-offs: GigaRAG vs. custom RAG vs. LangChain memory

I considered a custom RAG pipeline with Pinecone and a hand-rolled reranker. Rejected: it would have taken three weeks to build and tune, and the team didn't have the bandwidth to maintain it. GigaRAG gave me the same components in one API call.

I considered LangChain's memory module. Rejected: it couples memory to the framework and made swapping the retrieval backend painful. GigaRAG is a standalone service, so the agent code stays framework-agnostic.

Failure modes: context overflow, stale memory, retrieval misses

Context overflow. When a customer has 40+ memories, the top-k results can exceed the context window. Mitigation: cap memories at 8 per query and truncate each to 200 tokens.

Stale memory. Product changes make old answers wrong. Mitigation: the consolidation job flags entries older than 30 days for review, and retrieval scores decay with age.

Retrieval misses. When nothing clears the 0.72 threshold, the agent responds from documentation only and logs the query. I review the log weekly to find gaps in memory coverage.

Metrics: retrieval precision, memory hit rate, latency p95

• Retrieval precision: 0.88 on the eval set, measured monthly
• Memory hit rate: 74% across 1,200 test conversations
• Latency p95: 165ms end-to-end, including embedding and reranking
• Token cost per query: $0.014 including memory retrieval

These numbers are from a staging environment with 50,000 memory entries. Production numbers will differ, but the eval set stays fixed so I can track drift.

Common Mistakes When Writing an Architecture Memo for FDE Portfolio

Most architecture memos fail for the same five reasons. Reviewers see them repeatedly, and they're all avoidable.

Listing technologies without justifying choices

A stack list is not an architecture memo. Writing "Postgres, Pinecone, LangChain, FastAPI" tells a reviewer nothing about why those tools fit the problem. The justification is the signal. For every component, state the alternative you considered and the reason you picked what you picked. If you can't write that sentence, you haven't made a decision. You've made a default.

Omitting rejected approaches

The strongest section in the worked example above is the trade-offs section. It shows you evaluated options instead of grabbing the first thing that worked. Reviewers specifically look for this because it's the hardest thing to fake. If you only describe what you built, a reviewer can't tell whether you chose deliberately or stumbled into something that happened to work. Include at least two rejected approaches with the specific reason each one failed.

Writing for engineers who already know the system

You built the system, so every abbreviation and internal name feels obvious. It isn't. A reviewer reads your memo cold, with no context about your codebase, your team's history, or the constraints you absorbed over months. Define every acronym on first use. Spell out what each component does in one plain sentence. If a sentence only makes sense to someone who has seen your repo, rewrite it.

Ignoring failure modes and edge cases

A memo that only describes the happy path reads as naive. Production systems fail in predictable ways: timeouts, stale data, overflow, partial writes. A reviewer wants to see that you know how your system breaks and what you did about it. The failure modes section in the worked example is what separates a real architecture memo from a design fantasy. If you can't name three ways your system fails, you haven't run it long enough.

Making the memo too long or too vague

The two failure modes sit at opposite ends. A 4,000-word memo that documents every config flag buries the decisions that matter. A 400-word memo that says "we used a vector store for memory" skips the reasoning entirely. Aim for 1,200 to 2,000 words. Every paragraph should either state a decision, justify it, or describe a failure mode. If a paragraph does none of those, cut it.

How to Present the Architecture Memo in Your Portfolio

A memo nobody can find is a memo that doesn't count. Placement matters as much as content.

Where to put the memo: GitHub repo, personal site, or PDF

Put it in the repo root as ARCHITECTURE.md, linked from the README's first screen. That's where reviewers look first. A personal site works as a secondary home, but don't make it the only one. Reviewers won't hunt through your blog to find the doc that explains your project. PDFs are the worst option: they can't be updated inline, they don't render in GitHub's file browser, and they signal the memo is a one-time artifact rather than a living document.

Linking the memo to the code it describes

Every component named in the memo should link to the directory or file that implements it. If your memo says "the memory consolidation service runs as a background worker," that phrase should link to workers/consolidation.py. This lets a reviewer jump from your reasoning to your implementation in one click. It also proves the memo describes code that actually exists, not a design you sketched but never built.

Versioning the memo as the system evolves

The memo should change when the architecture changes. Commit it alongside the code that implements each change. A memo that describes the system as it was six months ago is worse than no memo at all. It tells a reviewer you document once and abandon. If you made a significant architectural shift, note the date and the reason in the trade-offs section rather than silently rewriting history.

Pairing the memo with a case study or post-mortem

The memo is the "what and why." A case study is the "what happened." Pair them. If you ran this system in production and something broke, write a short post-mortem and link it from the memo's failure modes section. That combination shows a reviewer you don't just design systems. You operate them, watch them fail, and learn.

What an Architecture Memo Cannot Demonstrate

An architecture memo is a document, not a performance. It shows how you think on paper. It cannot show how you think in a room.

It cannot prove you can code under pressure

A memo is written at your own pace, revised, and edited. It says nothing about whether you can produce working code while a clock runs and someone watches. Reviewers know this. They read the memo as a signal of design depth, then test coding speed separately in a live session. Don't expect the memo to carry that weight.

It cannot demonstrate collaboration or stakeholder management

The memo has one author: you. It doesn't show how you push back on a product manager, negotiate scope with a customer, or convince a senior engineer to abandon their preferred approach. Those skills show up in references, in how you talk about past projects, and in the interview itself. A memo can hint at them through trade-off language, but it can't prove them.

It cannot show how you handle production incidents in real time

A post-mortem describes what you did after an incident. A memo describes what you designed before one. Neither captures the moment itself: the alert firing, the pressure to restore service, the decisions made with incomplete information. If you want to demonstrate incident response, link a post-mortem. Even then, it's a reconstruction, not the event.

It cannot replace a live technical interview

No document can. The memo gets you the interview. It gives the interviewer a map of your thinking to probe. But the interview is where they test whether the reasoning in the memo holds up under questioning, whether you can defend the trade-offs you wrote down, and whether you can extend the design to a new constraint on the spot. The memo is the opening move, not the game.

How to Write the Architecture Memo This Weekend

You don't need a month. You need two focused days and a system you've already built. Here's the plan.

Day 1: Choose a system and draft the problem statement

Pick the system you know best. Not the most impressive one. The one where you can explain why you made each choice without looking anything up. Write one paragraph: what the system does, who uses it, and the single hardest constraint you faced. That's your problem statement. Don't polish it. Get it down.

Day 1: Fill in the template sections with bullet points

Open the template from earlier. For each section, write three to five bullets. Not prose. Just the facts: what you built, what you rejected, what failed, what you measured. If a section has no bullets after ten minutes, you either don't know the system well enough or the section doesn't apply. Both are useful signals.

Day 2: Expand bullets into prose and add trade-offs

Turn each bullet into two or three sentences. The trade-offs section gets the most attention: for every decision you made, name the alternative you considered and the specific reason you rejected it. Cost, latency, complexity, maintenance burden. Pick the real reason, not the flattering one.

Day 2: Review against the common mistakes checklist

Read the memo once, top to bottom. Check for the five mistakes from the previous section. If you listed a technology without saying why, fix it. If you skipped rejected approaches, add them. If a sentence would only make sense to someone who worked on the system with you, rewrite it. Then stop. Ship it.

Final Thoughts on Architecture Memos for FDE Portfolios

The architecture memo is the one artifact that separates a portfolio of projects from a portfolio of decisions. Code shows you can build. The memo shows you can choose.

What makes it work is the same thing that makes it hard: you have to write down what you rejected, not just what you shipped. Reviewers read the trade-offs section first. It's where the thinking lives.

The template and worked example in this guide give you the structure. The honest limitations section tells you what it won't do. Neither replaces the actual work of sitting down and writing out why you picked one approach over another.

If you're building an agent memory system with a RAG pipeline, GigaRAG gives you a concrete component to document. You can point to real ingestion, embedding, and retrieval decisions instead of hypothetical ones. That makes the memo easier to write and more convincing to read.

Write the memo this weekend. Ship it. Then start the next system. That's how you build an architecture memo for FDE portfolio reviewers who actually read.

Frequently Asked Questions

What is an architecture memo for an FDE portfolio?

An architecture memo is a concise document that explains the key architectural decisions behind a system you built, including context, alternatives considered, trade-offs, and consequences. In an FDE portfolio, it demonstrates your ability to reason about system design under real-world constraints, which is central to forward deployed engineering.

How long should an architecture memo be?

Aim for 1–3 pages. Reviewers spend limited time per portfolio item, so focus on the decisions and rationale rather than exhaustive detail. Use diagrams and bullet points to keep it scannable.

What should I include in the alternatives section?

List at least two realistic alternatives you considered, and explain why you rejected them in favor of your chosen approach. This shows you evaluated options rather than defaulting to the first idea, which is a key signal of architectural maturity.

Can I use an architecture memo instead of a README?

No—they serve different purposes. A README tells someone how to run and use your project, while an architecture memo explains why the system is designed the way it is. Include both in your portfolio for a complete picture.

How does an architecture memo differ from an ADR?

An Architecture Decision Record (ADR) captures a single decision at a point in time, often in a lightweight log format. An architecture memo is broader: it narrates the overall system context, multiple related decisions, and their combined trade-offs, making it better suited for portfolio presentation.

What can an architecture memo not demonstrate to reviewers?

It cannot prove that your code works, that the system performs under load, or that you can collaborate effectively in a team. Reviewers will look for code, demos, and evidence of teamwork elsewhere in your portfolio. The memo only showcases your design reasoning.

About GigaRAG

GigaRAG is for agent memory and RAG pipeline builders. get this right. Whether you are working through architecture memo for FDE portfolio or something adjacent, we publish what we have actually tested, including where it falls short.