That’s fine for a weather lookup. It’s not fine for an assistant that’s supposed to know who you are, where you live, who your contacts are, and what’s waiting on your reply.

Today we give our agent long-term memory: facts that persist across restarts, stored in a file the agent reads and writes itself — by calling memory tools, the same way it calls get_weather.

Two kinds of memory

Before we write code, it helps to be precise about what “memory” means for an agent:

• Working memory — the messages array from Part I. It’s the conversation context window. It dies when the process exits. We already have this.
• Long-term memory — persists beyond the run. This is the new concept. It splits further into semantic (key facts: “user lives in Tokyo”) and episodic (a journal of past interactions). Today we’re building semantic memory. Episodic and retrieval-based memory come later in the series.

The key design decision: the agent manages its own memory by calling tools. We don’t hard-code any extraction logic. The model decides what’s worth remembering and what to recall, just like it decides when to fetch the weather. Memory is just another tool in the loop.

Dependencies

We’re building on the Part I scaffold. If you still have your tutorial-part-1 project, you can reuse it. The only addition is Node’s built-in fs/promises module — no new install needed.

We’ll split our tools into a separate file this time, since the toolset is growing. Your project should look like:

tutorial-part-1/
├── main.ts
├── tools.ts
├── memory.json   ← created at runtime
└── package.json

The memory store

First, the persistence layer. We’ll use a simple JSON file with three categories — preferences, contacts, and open_threads. The first two are obvious; open_threads is a taste of where this series is heading (it will become the spine of a Slack triage agent in a later part).

Add this to tools.ts:

// tools.ts
import { readFile, writeFile, access } from "node:fs/promises";

const MEMORY_FILE = "memory.json";

async function loadMemory(): Promise<Record<string, Record<string, string>>> {
  try {
    await access(MEMORY_FILE);
    const raw = await readFile(MEMORY_FILE, "utf-8");
    return JSON.parse(raw);
  } catch {
    // First run — return a fresh schema
    return { preferences: {}, contacts: {}, open_threads: {} };
  }
}

async function persistMemory(mem: Record<string, Record<string, string>>) {
  await writeFile(MEMORY_FILE, JSON.stringify(mem, null, 2), "utf-8");
}

The try/catch around access handles the first-run case gracefully — no file yet, so we hand back an empty schema. This is the pattern you’ll see a lot: the agent’s first run is always a special case, and file-based stores handle it by treating “missing” as “empty.”

The memory tools

Now the two tools the agent will call. save_memory writes a fact; recall_memory reads one (or a whole category if no key is given):

export async function save_memory(
  category: string,
  key: string,
  value: string
): Promise<string> {
  const mem = await loadMemory();
  if (!mem[category]) mem[category] = {};
  mem[category][key] = value;
  await persistMemory(mem);
  return `Saved ${category}.${key} = ${value}`;
}

export async function recall_memory(
  category: string,
  key?: string
): Promise<string> {
  const mem = await loadMemory();
  if (!mem[category]) return `No memory in category "${category}".`;
  if (key) {
    const v = mem[category][key];
    return v ? `${category}.${key} = ${v}` : `No memory for ${category}.${key}`;
  }
  return JSON.stringify(mem[category], null, 2);
}

Note the return type: these tools return strings, not objects. The model reads tool results as text, so we serialize everything to a string before handing it back. This matters — if you return a raw object, the OpenAI client will stringify it, and you get [object Object] in the model’s context. Always return strings from tools.

Now the tool metadata. We’re keeping get_weather from Part I and adding the two memory tools. The descriptions are doing real work here — they tell the model when to use each tool and what categories exist:

export const metadata = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description:
        "Fetch current weather for a location. You may pass just a city name (e.g. 'Tokyo'), or add a country/region qualifier after a comma to disambiguate (e.g. 'San Francisco, US' or 'Portland, Oregon').",
      parameters: {
        type: "object",
        required: ["location"],
        properties: {
          location: {
            type: "string",
            description:
              'City name, optionally with a country/region after a comma, e.g. "Tokyo", "San Francisco, US", or "Portland, Oregon".',
          },
        },
      },
    },
  },
  {
    type: "function",
    function: {
      name: "save_memory",
      description:
        "Persist a fact about the user for later recall. Use category 'preferences' for things like location and units, 'contacts' for people, and 'open_threads' for things waiting on the user's reply.",
      parameters: {
        type: "object",
        required: ["category", "key", "value"],
        properties: {
          category: {
            type: "string",
            description: "One of: preferences, contacts, open_threads",
          },
          key: { type: "string", description: "A short identifier for the fact" },
          value: { type: "string", description: "The fact to remember" },
        },
      },
    },
  },
  {
    type: "function",
    function: {
      name: "recall_memory",
      description:
        "Recall a previously saved fact. Pass a category and optional key. If key is omitted, returns everything in that category.",
      parameters: {
        type: "object",
        required: ["category"],
        properties: {
          category: { type: "string", description: "One of: preferences, contacts, open_threads" },
          key: {
            type: "string",
            description: "Optional specific key; omit to recall the whole category",
          },
        },
      },
    },
  },
];

Two ways to load memory

There are two patterns for getting memory into the agent’s context, and we’ll use both:

Startup injection — read memory.json once when the program boots and append it to the system prompt. The agent knows your preferences before the first turn. This is cheap (one file read) and good for small, always-relevant facts like location and units.

In-turn recall — the agent calls recall_memory during a conversation when it needs something specific. This is better for large or selectively-relevant memory (you don’t want to dump your entire contact list into the system prompt every run).

For Part II we’ll use startup injection for preferences (small, always useful) and leave in-turn recall for the agent to discover on its own. Here’s the startup loader:

// main.ts
import OpenAI from "openai";
import { createInterface } from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
import { readFile, access } from "node:fs/promises";
import { metadata, get_weather, save_memory, recall_memory } from "./tools";

const SYSTEM_PROMPT = `You are a personal weather assistant with memory.

You can remember facts about the user by calling save_memory, and recall them by calling recall_memory.
Memory categories: "preferences", "contacts", "open_threads".

If the user tells you a durable fact about themselves (where they live, their temperature unit preference, who they know), save it.
If the user asks for the weather without naming a city, recall their location from memory first.

When you report weather for a location, use exactly this format and nothing else:

Here is the weather information for <city>, <country>:

🌡️ <temp>°C
💨 wind <speed> km/h
☁️ cloud coverage <cloud coverage>%

If the lookup failed, reply with exactly one line:
⚠️ <one concise sentence explaining why>

Do not add greetings, extra commentary, or markdown code fences.`;

const MODEL = "qwen/qwen3-4b";

const client = new OpenAI({
  baseURL: "http://localhost:1234/v1",
  apiKey: "dummy_value",
});

async function loadMemoryContext(): Promise<string> {
  try {
    await access("memory.json");
    const raw = await readFile("memory.json", "utf-8");
    const mem = JSON.parse(raw);
    const prefs = mem.preferences || {};
    if (Object.keys(prefs).length === 0) return "";
    return `\n\nKnown user preferences: ${JSON.stringify(prefs)}`;
  } catch {
    return "";
  }
}

We inject only preferences at startup — small and always relevant. Contacts and open_threads stay on disk for the agent to recall on demand.

Fixing the loop

In Part I our tool handling was one-shot: call the model once, execute any tools, call the model once more, done. That breaks the moment the agent needs to chain calls — for example, recall a memory and then fetch weather based on what it remembered.

We need a real inner loop: keep calling the model and executing tools as long as it keeps requesting them. Here’s a single dispatcher for all our tools, then the loop:

async function executeTool(name: string, args: any): Promise<string> {
  switch (name) {
    case "get_weather":
      return await get_weather(args.location);
    case "save_memory":
      return await save_memory(args.category, args.key, args.value);
    case "recall_memory":
      return await recall_memory(args.category, args.key);
    default:
      return `Unknown tool: ${name}`;
  }
}

Two things every tool call shares: await (these are all async) and string returns (enforced by the function signatures). Centralizing dispatch means we can’t accidentally forget an await or mistype a tool name in the loop body.

Now the main loop:

async function main() {
  const rl = createInterface({ input, output });
  rl.on("SIGINT", async () => {
    rl.close();
    process.exit(0);
  });

  const memoryContext = await loadMemoryContext();
  const messages = [{ role: "system", content: SYSTEM_PROMPT + memoryContext }];

  while (true) {
    let user_input = await rl.question("You> ");
    user_input = user_input.trim();
    if (user_input === "quit") break;

    messages.push({ role: "user", content: user_input });

    // First completion
    let reply = (
      await client.chat.completions.create({
        model: MODEL,
        messages,
        tools: metadata,
      })
    ).choices[0].message;
    messages.push(reply);

    // Inner loop: execute tools and re-prompt until the model stops calling tools
    while (reply.tool_calls && reply.tool_calls.length > 0) {
      for (const toolCall of reply.tool_calls) {
        const args = JSON.parse(toolCall.function.arguments || "{}");
        const result = await executeTool(toolCall.function.name, args);
        messages.push({
          role: "tool",
          tool_call_id: toolCall.id,
          content: result,
        });
      }
      reply = (
        await client.chat.completions.create({
          model: MODEL,
          messages,
          tools: metadata,
        })
      ).choices[0].message;
      messages.push(reply);
    }

    console.log(`Assistant> ${reply.content}\n`);
  }
}

main();

Two details matter here, and both bite silently if you get them wrong:

1. Push the assistant’s tool_calls message before the tool results. See messages.push(reply) right after the first completion. The API requires every role: "tool" message to follow the assistant message that requested the call. Skip this and you get a 400 error.
2. await every tool call. Our tools are async. Without await, result is a Promise, which serializes to "[object Promise]" in the model’s context. The model will happily hallucinate a response based on that garbage. tsx doesn’t type-check, so nothing catches this at runtime — it just degrades quietly.

The inner while loop is the heart of it. The model calls tools, we execute them, we hand the results back, and the model decides whether to call more tools or produce a final answer. This is what lets the agent reason through steps — recall memory, then fetch weather, then format — all in one turn.

The demo

Start the agent fresh (no memory.json yet) and tell it about yourself:

You> I live in Tokyo, and I prefer Celsius.
Assistant>

Got it — I've saved that you live in Tokyo and prefer Celsius. 🌡️

Check memory.json — the agent wrote it:

{
  "preferences": {
    "location": "Tokyo",
    "units": "Celsius"
  },
  "contacts": {},
  "open_threads": {}
}

Now ask for the weather without naming a city:

You> What's the weather?
Assistant>

Here is the weather information for Shikinejima, Japan:

🌡️ 26°C
💨 wind 36 km/h
☁️ cloud coverage 25%

The agent recalled “Tokyo” from memory, then called get_weather — a chained tool call that Part I’s one-shot loop couldn’t have done.

Now the payoff. Quit the program (quit), close the terminal, come back tomorrow. Start it again:

You> What's the weather?
Assistant>

Here is the weather information for Shikinejima, Japan:

🌡️ 24°C
💨 wind 14 km/h
☁️ cloud coverage 10%

It still knows where you live. The memory survived the restart because it lives in a file, not in the messages array.

Memory that grows

Let’s show the schema doing real work. Tell the agent about a contact and something waiting on you:

You> Sarah Chen is my engineering manager, she owns the Q3 roadmap.
Assistant>

Saved Sarah Chen to contacts.

You> I'm waiting on Sarah about the Q3 staffing decision — she needs my answer by Friday.
Assistant>

Got it — I've saved that as an open thread: Sarah Chen, Q3 staffing decision, due Friday.

{
  "preferences": { "location": "Tokyo", "units": "Celsius" },
  "contacts": {
    "sarah_chen": "Engineering manager, owns the Q3 roadmap"
  },
  "open_threads": {
    "sarah_q3_staffing": "Waiting on Sarah Chen about Q3 staffing decision — answer needed by Friday"
  }
}

That open_threads entry is a seed. In a later part of this series, when we connect this agent to Slack, open_threads becomes the backbone of a triage assistant: the agent will read your unread messages, match them against open threads, and tell you what actually needs your attention today. But that’s later — for now it’s just the agent remembering what you told it to remember.

What we built

We now have an agent that:

• Persists facts about you across restarts, in a file it reads and writes itself
• Injects known preferences at startup so it has context before the first turn
• Recalls memory mid-conversation when it needs something specific
• Chains tool calls (recall → fetch → format) thanks to the inner loop

What we’re not doing yet

• Retrieval over a large corpus. Our memory is a flat JSON file. Once you have hundreds of contacts and thousands of past messages, you can’t dump it all into the system prompt. You need semantic search — embeddings and a vector store. That’s a later part.
• Episodic memory. We store facts, not a history of what happened. “What did Sarah say about the roadmap last March?” needs episodic memory backed by retrieval. Also later.
• Concurrency. The read-modify-write on memory.json is not safe if two agents hit it at once. Fine for a single-user CLI assistant; a problem later.

Next time we’ll connect this agent to a real external surface — Slack — and turn open_threads from a static list into something the agent keeps updated by reading your messages.

This guide follows my work understanding loop engineering. As I want to learn from the fundamentals I am building this tutorial part series under my blog where I will progressively cover more advanced concepts from the ground up.

Today we will build a simple weather assistant which will be a simple agentic loop with a tool call for fetching the weather in a city.

Dependencies

There are a few dependencies we will need to follow along

1. Typescript Project Scaffold

You will need to create a base project. In this case I am creating a very simple project scaffold using three package including openai which will use below

mkdir tutorial-part-1 && cd tutorial-part-1
npm i -D typescript tsx openai
npx tsc --init

After installing the dependencies copy and paste the following into package.json

{
  "type": "module",
  "scripts": {
    "dev": "npx tsx main.ts"
  },
  "devDependencies": {
    "openai": "^6.45.0",
    "tsx": "^4.23.0",
    "typescript": "^6.0.3"
  }
}

Then create your main.ts file

console.log("Hello World!")

Finally run npm run dev to see if the project works

2. LLM Studio Desktop

Grab the latest version of LLM Studio (https://lmstudio.ai/) and we will build an agent that uses a local model.

Once you boot up you will want to download a light-weight model (one that supports tool calling). Note, I am using qwen-3-4b for the examples below

Getting Started

An agentic loop contains the following:

• The loop (in this case a while loop)
• The LLM model for generating responses based on an input
• Available tool calls e.g. in our case today get_weather

Here is an example of the most simple agentic loop (minus tool calling):

import { createInterface } from "node:readline/promises"
import { stdin as input, stdout as output } from "node:process";

const SYSTEM_PROMPT = `You are a weather assistant`;
const MODEL = 'qwen/qwen3-4b';

const messages = [{ role: "system", content: SYSTEM_PROMPT }];

async function main() {
  const rl = createInterface({ input, output });
  
  // Gracefully handle CTRL+C on CLI
  rl.on("SIGINT", async () => {
    rl.close();
    process.exit(0);
  })
  
  // The agentic loop
  while (true) {
    let user_input = await rl.question("You> ");
    user_input = user_input.trim(); // Strip any whitespace
    
    // Check if user has typed "exit"
    if (user_input == "quit") break;
    
    // Push the users question onto our context
    messages.push({ role: "user", content: user_input });
    
    // Mock out an LLM response from the user input
    let mocked_response = { role: "assistant", content: "Hello!" };
    messages.push(mocked_response);
    
    console.log(`Assistant> ${mocked_response.content}\n\n`);
  }
}

Prompting the LLM model

The first step to prompting a real LLM is to initialize an OpenAI wrapper so we can communicate with LMStudio. LMStudio supports OpenAI’s API under the hood and allows us to route to local models using it.

You will need to enable the “Developer Server” and in “Server Settings” and listen on your local network. It should then give you an IP address to make requests.

Once you have the IP address the server is binded on you can copy and paste this into the OpenAI wrapper as follows (note, a dummy password should be okay if password protection is disabled):

const client = new OpenAI({
  baseURL: "http://100.121.13.119:1234/v1",
  apiKey: 'dummy_value'
});

Next let’s replace the mocked call out example above with an OpenAI completion request:

// Call our model and push the response to messages
const completion = await client.chat.completions.create({
  model: MODEL,
  messages,
});
const reply = completion.choices[0].message;
messages.push(reply);

We should now be able to have a conversation with our agent now :)

You> Hello
Assistant>

Hello! How can I assist you today? If you need weather information or have any questions about the forecast, feel free to ask! 🌤️ 

You> What's the weather, right now, in Tokyo, Japan.
Assistant>

I currently don’t have access to live weather data or internet resources to provide the exact current weather in Tokyo. However, I can share that Tokyo typically has a humid subtropical climate, so:

- **Summer** (June–August): Hot and rainy, with temperatures often exceeding 30°C (86°F).
- **Winter** (December–February): Mild and mostly sunny, with temperatures averaging around 10–15°C (50–59°F).

For the most accurate and up-to-date information, I recommend checking a reliable weather service like [AccuWeather](https://www.accuweather.com) or [The Weather Channel](https://www.weather.com). Let me know if you’d like help with something else! 🌤️ 

Adding tool calls

In the example above our LLM doesn’t have the ability to call tools so when its asked for real-time data it doesn’t work.

Will expand our program to include a tools.ts file which will contain define our tool available to our agent:

// tools.ts
export const metadata = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description:
        "Fetch current weather for a location. You may pass just a city name (e.g. 'Tokyo'), or add a country/region qualifier after a comma to disambiguate (e.g. 'San Francisco, US' or 'Portland, Oregon').",
      parameters: {
        type: "object",
        required: ["location"],
        properties: {
          location: {
            type: "string",
            description:
              'City name, optionally with a country/region after a comma, e.g. "Tokyo", "San Francisco, US", or "Portland, Oregon".',
          }
        }
      }
    }
  }
];

Next in main.ts import the tools and pass them into the completions API call:

import { metadata } from "./tools"

const completion = await client.chat.completions.create({
  model: MODEL,
  messages,
  tools: metadata // <---------
});

As an experiment we can now ask our model if it has access to any tools:

You> What tools do you have access to?
Assistant>

I have access to a weather tool that allows me to fetch current weather information for any location. You can simply provide a city name (e.g., "New York") or specify a location with country/region details (e.g., "London, UK" or "Sydney, Australia"). Would you like me to check the weather for a specific place?

At this point if you ask for the weather in a specific city it will return nothing as we have not defined the function yet. Let’s define get_weather:

// tools.ts
export async function get_weather(location: string): Promise<string> {
  try {
    // Native fetch with an 8-second timeout inline
    const res = await fetch(`https://wttr.in/${encodeURIComponent(location)}?format=j1`, {
      signal: AbortSignal.timeout(8000)
    });
    
    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
    const wx = await res.json();
    
    const current = wx.current_condition?.[0];
    const area = wx.nearest_area?.[0];
    if (!current || !area) return `Weather data unavailable for ${location}.`;

    const name = area.areaName?.[0]?.value || location;
    const country = area.country?.[0]?.value || "";
    const { temp_C: temp, windspeedKmph: wind, cloudcover: clouds } = current;
    const condition = current.weatherDesc?.[0]?.value || "Unknown";

    return `${name}${country ? `, ${country}` : ""}: ${temp}°C, wind ${wind} km/h, cloud coverage: ${clouds}% (${condition})`;
  } catch (err) {
    return `Sorry, I couldn't fetch the weather for "${location}" right now (${err instanceof Error ? err.message : err}). Please try again shortly.`;
  }
}

Once defined you will need to handle the first response from our LLM model which will ask to invoke tooling.

You can do this by checking the reply from the first completion and looping through tool_calls array in the reply:

// Call our model with our user input
const completion = await client.chat.completions.create({
  model: MODEL,
  messages,
  tools: metadata
});
const reply = completion.choices[0].message;

// Check if the model requested any tool calls
if (reply.tool_calls && reply.tool_calls.length > 0) {
  for (const toolCall of reply.tool_calls) {
    if (toolCall.function.name == "get_weather") {
      const args = JSON.parse(toolCall.function.arguments)
      const toolResult = await get_weather(args.location);
      
      messages.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: toolResult
      });
    }
  }
}

// Finally follow up with results from any tools calls or initial output
const followup = await client.chat.completions.create({
  model: MODEL,
  tools: metadata,
  messages,
});
const finalMessage = followup.choices[0].message;
messages.push(finalMessage);

You should now be able to see the result inside the reply:

You> What's the weather in Tokyo?
Assistant>

The current weather in Tokyo is 26°C, with winds at 36 km/h and light cloud coverage of 25%.

Fixing the format

If we don’t fix the format of our agent it will always come up with some unique response. That’s usually undesirable if were trying to get deterministic results.

We can fix this with a slight system prompt update

const SYSTEM_PROMPT = `
You are a weather assistant.

When you report weather for a location, your reply to the user MUST use exactly this format and nothing else:

Here is the weather information for <city>, <country>:

🌡️ <temp>°C
💨 wind <speed> km/h
☁️ cloud coverage <cloud coverage>%

If the lookup failed for any reason, reply with exactly one line:
⚠️ <one concise sentence explaining why>

Do not add greetings, extra commentary, or markdown code fences.
`;

Now let’s try again

You> What's the weather in Tokyo?
Assistant>

Here is the weather information for Shikinejima, Japan:

🌡️ 26°C
💨 wind 36 km/h
☁️ cloud coverage 25%

Perfect. That’s it for the first tutorial. We now have an agent that will tell us the weather to any location in a fixed format. If you can imagine we can create much more complex agents. Once they have the ability to call tools we can do some pretty complicated stuff!

When I was promoted to CTO at a much larger company that’s when I struggled. One of the biggest challenges was actually the title itself. In my case, I went from being a productive engineer to worrying about how others viewed me at the company and if I was living up to expectations. Your classic case of Imposter syndrome .

How long did it take me to overcome my imposter syndrome? About two years! and a lot of sleepless nights. Luckily for me I had a good mentor with a lot of patience. I still don’t feel comfortable on some days but I’ve learned to trust that usually means your heading in the right direction.

Looking back there were a few pointers I wish I knew beforehand that I want to share.

Technical CTO or Manager CTO

The biggest problem with the CTO title is that no one really defines the role for you. The reality is the job changes as the needs of your company change.

If you are confused about what to do next, ask yourself what your organization is lacking and head in that direction. For me, we needed talent so I focused heavily on recruiting one quarter. When we brought in competent engineers I focused on mentorship and performance. Then one quarter I was back working on technical side of things.

The reality is your role will change with the company so there isn’t a guidebook on being successful in this role.

Don’t Lead by Title

Don’t refer to yourself using your title. I have found titles are good for rewarding hard work but have little meaning in modern organizations.

Introduce yourself as a “team lead” or “leading the engineering teams at X company”. I still remember introducing myself during a meeting with a client. I was quickly met by a sarcastic ” Whoa, we’re talking to a CTO!”. It leaves a weird awkwardness which is not really needed in the first place.

It’s better to ditch the title early and talk to people on the same level. I would even go as far as removing it from your business card.

It sounds simple enough but it’s hard to drop your ego if you have one. The faster you can forget about your title the quicker you can get on with real work!

People Pleasing

I do and still often like to please people. This has helped me succeed quickly in my early career as a software developer as I would take on large amounts of work to please upper management.

When you become responsible for people this strategy quickly backfires on you. I was lucky enough to get direct feedback from a peer and course correct early.

If you don’t know what people pleasing looks like here are a few signs:

• You settle for mediocre because you don’t want hurt an engineers feelings.
• You try to make excuses for low performers and lower their bar compared to the rest of the team.
• You find yourself running around trying to please an engineer that is upset with your company culture.

Heed this warning, if you are too nice you don’t communicate direct feedback your team members desperately need to improve. Worse, you keep a disruptive team member in your company longer.

Mind Games

Jealously, fear, anxiety, I have these all and my mind still messes with me. However, if you can push through the discomfort and accept failure as a learning experience you quickly adapt and don’t get easily phased when there’s problems.

Conclusion

Congratulations on the promotion, your challenge in the new role will be yourself! My advice, keep calm and try things that make you uncomfortable, this is the best way to learn and the quickest way to build a hard skin.

I purchased my first build kit the Mint60 which a split keyboard. The 60 standing for the 60% keyboard layout which is a popular form factor for hobby keyboards.

My Mint60 build kit comes with the following:

• A transparent keyboard casing
• Screws (spacer x20, 5mm x 28, 8mm x 12)
• CherryPCB Stablisers x5
• ProMicro Arduino x2
• TRRS Audio Jack x2
• RGB LED Strip
• Reset Switch x2
• And a lot of resistors

(Image credit Yusha Kobo)

Note, build kits sold at Yusha Kobo (and most online stores) don ‘t include key switches or key caps. These have to be purchased seperately with your kit. The Mint60 has 66 keys so I needed to purchase 66 switches and the key caps seperately.

What do I need to put a kit together?

• A keyboard starter kit (includes a pcb, mirocontroller, keyboard stablizers, case, etc.)
• Your own keyboard switches and caps (If not included in your kit)
• Soldering gear (solder, soldering iron, copper wick)
• A pair for small wire cutters
• A multi-meter for debugging (optional)
• A lot of patience

Note, you probably won’t need a multi-meter but it may help if you made mistakes soldering. I ended up using a multi-meter to test my switches and some components for continuity .

Key switches

One of the most rewarding parts of building your own keyboard is selecting your own key switches. Here’s a great YouTube video for finding the right switch for you.

In the end I chose Cherry MX red switches (80 for around 3000 JPY) at Yusha Kobo. These are soft to press and don’t make much noise.

Keyboard caps

For this build I chose Tai-Hao PBT Hawaii keycap set which I bought at Yusha Kobo.

(Image credit Yusha Kobo)

Before you get started

• Solder your microcontroller LAST! *

If you’re stupid like me you might solder your microcontroller on before your key switches. Don’t be stupid like me.

Once you solder on the microcontroller you can no longer solder any key switches above it. This may not be true for most kits but this was the case for the Mint60 kit I bought 🤦

• Make sure your switches are soldered in completely *

When I put everything together and plugged the keyboard in I noticed some keys didn’t work. Taking a closer look you can see a small gap in the pin hole which holds the key switch.

When soldering you should always make sure to cover pin holes completely in solder otherwise they can spring loose which is what happened here.

When soldering you want to make sure you cover each pin hole completely in solder and have a nice cone shape like the pin on the right in the above photo.

Getting started

The first thing is soldering in resistors. If your PCB does not have these soldered in already you will have to manually do this. Resistors are needed to prevent voltage from fluctuating and randomly triggering key presses. More on why resitors are needed here .

I pain-stakingly bent each individual resistor to fit it into the board. A quick trick that will save you time is to find a book or edge and bend all the resistors at the same time. This will ensure you can quickly slide all the resisters into the pin holes on your board.

Once you slide in the resistors into the board, bend the bottoms so they don’t fall out

Afterwards solder the pin hole down and cut off the excess legging with wire cutters

Soldering on the key switches

Your kit should come with a plate where you can start mounting your switches to your board.

Be careful at this step. Once you’ve decided on a layout you won’t be able to easily de-solder the key switches again. It’s possible, but will suck.

Note, the black areas surrounding the larger keys are calledstablisers . These ensure longer keys like spacebar or backspace don’t fly off when pressed on the side. These are held in place through small holes in the PCB. At least, this was the case on my board.

Once you have decided on your choice of layout and swtiches you can start soldering the key switches onto the board. Also make sure the small white circle on the back of your key switch is flush against the backside of the PCB. I recommend using small clamps to hold the board in place before soldering.

Flash your microcontroller

Your kit should come with a microcontroller. The most popular microcontroller for keyboards looks like the Arduino Pro Micro .

I went a bit crazy when I built my first kit. I had soldered everything onto the board and plugged it in. Nothing. Keys were not registered. No LED lights. This is because most kits dont flash the microcontroller. You will need to flash the firmware onto the microcontroller otherwise nothing will work.

I used QMK for flashing my microcontroller. This is a free open source project for hardware keyboards. Flashing the microcontroller is easy using QMK. You just plug it into USB and run the QMK software and select your keyboard model. Most hobby boards have their software already included in the QMK repository so flashing is easy.

Soldering on the remaining components

After you made sure your microcontroller can be flashed its time to solder the rest of the components down. For me, this meant the TRRS audio jack for my split keyboard, a microcontroller, and a small RGB LED strip

(image credit to eucalyn’s Mint60 guide)

Make sure your key switches work

Once your microcontroller has been flashed and soldered you can start testing each key switch. This is good idea before closing the keyboard up. If one key does not respond it may need to be resoldered. I had several switches which needed to be resoldered on my first build because I didn’t use enough solder.

After that you need some software for testing. If you are on OSX I recommend using Karabiner EventViewer . Once installed you can check each individual key and make sure it maps to the correct key. A word of warning though the “fn” key will not register unless you press it in combination with another key.

Put on your key caps!

Almost there! Once you’ve verified your board works you can start putting the key caps on it!

Customization keymaps

After you get your board setup you will want to start customizing the layout a bit. This is pretty simple once you can get QMK compiling locally. After you can compile the project you can simply modify the keymap inside QMK. I ended up modifying my original keymap with my own mappings.

I would defintely recommend reading the noob guide to QMK before jumping in to get an idea of the full set of features: https://beta.docs.qmk.fm/newbs/newbs_getting_started

Conclusion

It turns out building a mechanical keyboard is actually not that difficult. I had a difficult time because I didn’t read my kits instructions and I paid for it with hours of de-soldering…

In the end, a keyboard is just a bunch of switches. The circuit is quite simple and easy to understand. It’s essentially a bunch of arduino buttons rigged together if you’ve every done anything with the Arduino it should be quite simple.

Eventually I want to design my own PCB layout. However, for the time being I’m quite happy with form factors most hobby kits offer :)

It wasn’t a spontaneous decision to move to Japan. I loved Japan and had been planning most of my early 20’s on how to move there. I knew I needed a univeristy degree, so I got one. I also took some Japanese language classes along the way.

I am here today because I set goals for myself. I worked hard to achieve those goals and eventually was able to move to Japan. Having a strong goal can be a powerful thing and make you push to your limits.

Now that it’s 2020 I feel its time to start planning again much like I did in my early 20’s. I will set some new goals for myself. So, without further adieu.

On Writing

The people I look up to are all great writers. They knew how to write and share their ideas with the world through their words. Writing is powerful, I know that now and want to improve.

I feel my writing skills have always been weak. Over the years I’ve written a few articles but could never really establish a habit to level-up my writing.

This year I want to write one blog post each month to improve my writing skill. Eventually, someday, I would love to write a book.

On Reading

Going back to the people I admire, Bill Gates, who takes solo ‘think weeks’ in a cabin in the woods to consume books. Just like him I want to learn and apply knowledge from books to make real change in the world.

I plan to take my own ‘think week’ this year. I also plan to read at least 12 books by the end of 2020. I’ve setup goodreads reading list to track my progress.

Japanese

Someone I respect told me after 10 years of living in a foreign country if you still don’t speak the language you never will. This scares me. I’m seven years in to my life in Japan and not fluent yet.

My target for this year is to pass the JLPT N3 exam. I have passed N4 and N5 levels but it’s not conversational Japanese. The N3 is a big deal for me because it means I can hold my own when speaking Japanese. It’s really the point where I can say I can speak Japanese.

On My Health

Being healthier has loads of benefits. You sleep better, you feel better, and generally just have more energy to do awesome work.

I’m currently overweight and this is making me sleep worse which is degrading my life experience. This year I want to eat right and achieve a healthy target weight by the end of 2020.

On Being Human

The last decade I focused mostly on myself and my own ego. This year I want to help others and be more empathetic to other human beings. I also want to drop my ego.

So this year I will focus on making new friends and improving my existing relationships. As a leader of a team I want to mentor others and give everyone a chance to grow, beyond me.

Looking Forward

I think we all need some accountability if we want to acheive a goal. I definiately didn’t keep my Japan dream secret. I told everyone until a co-worker finally had enough and said “Why are you still here? Goto Japan already!”. I left pretty quickly after that. I imagine if someone didn’t hold me accountable thought if I would of ever had the courage to make a leap.

For a little bit of accountability I wrote this article. I see it as a way to publically tell the world I am serious this time and I will accomplish the goals:

• To write one blog post a month
• To read one book once a month
• To take one ‘think week’ this year
• To live healthier (lose 8kg by end of 2020)
• To make new friendships and improve my current ones