DEV Community: Christopher S. Aondona

Building Memory-Native AI Agents in TypeScript with MemoFS

Christopher S. Aondona — Fri, 07 Aug 2026 09:37:49 +0000

Most developers building custom AI agents spend weeks attempting to solve memory management manually:

They set up vector database wrappers.
They craft ad-hoc chunking logic.
They struggle with memory staleness, secret filtering, and context window blowup.

@memofs/core provides an open-source, production-ready TypeScript SDK that gives any custom AI agent durable, file-first persistent memory in just a few lines of code.

Because @memofs/core uses the canonical .memofs/ workspace directory, memories persisted by your custom TypeScript agents seamlessly co-exist with end-user developer tools (Claude Code, Cursor, Copilot, Codex, e.t.c). Developers can inspect agent memory using plain text tools or npx memofs, while custom agent frameworks share a single source of truth across the codebase.

In this tutorial, we will build a memory-native TypeScript agent that retains knowledge across sessions, automatically sanitizes sensitive data, executes task-aware recall, and updates stale facts cleanly.

Installation

Add @memofs/core to your project:

npm install @memofs/core
# or
pnpm add @memofs/core

Note: @memofs/core requires Node.js >= 22.

1. Initializing the MemoFS Engine

The core engine is instantiated using the MemoFS class and a Node filesystem storage store (createNodeFsMemoryStore from @memofs/core/node-fs).

import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

// 1. Initialize local filesystem storage root
const store = createNodeFsMemoryStore({
  rootDir: process.cwd(),
});

// 2. Instantiate MemoFS memory engine
const memo = new MemoFS({
  store,
  projectId: "my-custom-agent",
  mode: "local", // 'local' | 'hybrid'
});

Alternatively, Node consumers can use the createNodeMemoFs helper:

import { createNodeMemoFs } from "@memofs/core/node-fs";

const memo = createNodeMemoFs({
  rootDir: process.cwd(),
  projectId: "my-custom-agent",
  mode: "local",
});

Storage Modes Supported by `@memofs/core`

local: Offline storage. Memory reads and writes execute directly against local .memofs/ files with zero network requests.
hybrid: Writes files locally for speed, but asynchronously syncs replicas to MemoFS Cloud for cross-machine access.

2. Generating Task-Aware Context Briefings

Before executing an agent task, retrieve a compact, structured memory briefing to inject into your LLM system prompt using memo.context().

async function buildAgentSystemPrompt(userTask: string): Promise<string> {
  // Query MemoFS for task-aware context
  const contextResult = await memo.context({
    query: userTask,
    taskType: "refactor", // 'coding' | 'debug' | 'refactor' | 'docs' | 'general'
    maxBytes: 12000,
  });

  return `
You are an autonomous coding agent.

## PROJECT MEMORY BRIEFING
${contextResult.text}

## USER TASK
${userTask}
`;
}

MemoFS formats the briefing automatically, categorizing output into Core Rules, Relevant Historical Notes, and Active Constraints while keeping total size under your specified maxBytes cap.

3. Writing Durable Memories with Secret Filtering

When your agent makes a design decision, discovers a constraint, or completes a task, persist it using memo.writeMemory().

async function recordAgentDecision(decisionText: string, category: "decision" | "constraint" | "note") {
  const result = await memo.writeMemory({
    content: decisionText,
    kind: category,
    tags: ["architecture", "auth"],
  });

  if (result.tier !== "durable") {
    console.warn(`Memory stored as ${result.tier} (reason: ${result.tierReason}).`);
    return;
  }

  console.log(`✓ Durable memory persisted cleanly with ID: ${result.id}`);
}

// Example invocation:
await recordAgentDecision(
  "Database queries must use Drizzle ORM prepared statements for SQL injection safety",
  "constraint"
);

Built-in Safety & Sanitization

Before writing to .memofs/memory/notes.md, @memofs/core automatically executes:

Secret Blocklist Pass: Rejects API keys (sk-...), JWTs, and private tokens up front (unless --allow-secrets / explicit flags are passed).
Deterministic Durability Classification: Determines whether the fact has long-term value (durable) or single-turn relevance (transient).

4. Handling Stale Memory with Graph Relationships

When an architectural fact changes, avoid creating conflicting memories. Write the new memory and link the relationship in the entity graph via memo.graph.upsertEdges():

async function updateStaleFact(oldMemoryId: string, newFactText: string) {
  // 1. Write the new decision
  const result = await memo.writeMemory({
    content: newFactText,
    kind: "decision",
    tags: ["auth"],
  });

  // 2. Link the new memory as superseding the old memory in the relationship graph
  await memo.graph.upsertEdges({
    edges: [
      {
        source: result.id,
        target: oldMemoryId,
        type: "supersedes",
      },
    ],
  });

  console.log(`✓ Created new memory ${result.id} superseding ${oldMemoryId}`);
}

MemoFS updates .memofs/graph/edges.jsonl. Subsequent queries automatically surface the newest fact while preserving historical context for auditability.

5. End-to-End Example: Complete Agent Loop

Here is a full working agent loop demonstrating memory-native context injection, execution, and memory persistence:

import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

async function runMemoryNativeAgent(userPrompt: string) {
  // 1. Initialize Memory Engine
  const store = createNodeFsMemoryStore({ rootDir: "." });
  const memo = new MemoFS({
    store,
    projectId: "agent-demo",
    mode: "local",
  });

  // 2. Retrieve Memory Briefing
  const context = await memo.context({ query: userPrompt, taskType: "coding" });

  console.log("--- INJECTED MEMORY BRIEFING ---");
  console.log(context.text);

  // 3. Perform Agent Task (Simulated LLM response)
  console.log("Executing agent task...");

  // 4. Persist Learned Fact to MemoFS
  const writeResult = await memo.writeMemory({
    content: "Session tokens expire in 15 minutes",
    kind: "decision",
    tags: ["auth", "security"],
  });

  console.log(`✓ Session complete. Memory persisted to .memofs/ with ID: ${writeResult.id}`);
}

runMemoryNativeAgent("Refactor our user session timeout");

Summary of Core API Reference

Method	Description
`memo.context({ query, taskType, maxBytes })`	Generates a compact system prompt briefing.
`memo.writeMemory({ content, kind, tags })`	Filters secrets, classifies durability, and persists structured memory.
`memo.recall(query, { limit })`	Executes hybrid recall (BM25 + fuzzy + vector) over stored memory chunks.
`memo.consolidate()`	Runs background deduplication and graph cleanup over `.memofs/`.

Resources & Documentation

Supercharging AI Coding Agents & Custom Agent Runtimes with Persistent Memory: A Detailed Cookbook

Christopher S. Aondona — Sat, 01 Aug 2026 08:55:31 +0000

Whether you use pre-built AI coding tools like Claude Code, OpenAI Codex, OpenCode, and Cursor, or you are building custom autonomous agent runtimes in TypeScript, every agent environment suffers from the same limitation:

Every new chat or execution trajectory starts with zero knowledge of past decisions.
Switching git branches or spawning subagents confuses the agent about active dependencies.
When an agent compacts its context window to manage token limits, it erases the rules established earlier.

This guide is a practical cookbook for attaching MemoFS—the open-source, file-first memory runtime—to any AI coding agent or custom agent runtime in under two minutes.

Cookbook Overview: How MemoFS Connects to Agents

MemoFS supports three integration patterns depending on your tool or framework:

┌───────────────────────────────────────────────────────────────────────────┐
│                          AI Agent Ecosystem                               │
└──────────────┬─────────────────────────────┬──────────────────────────────┘
               │                             │                              │
     (Agents with Hooks)            (Agents via MCP)           (Custom Agent Runtimes)
   Claude Code / Codex / OpenCode  Cursor / Copilot / Windsurf    TypeScript / LangChain / SDKs
               │                             │                              │
               ▼                             ▼                              ▼
     Lifecycle Hook Scripts           @memofs/mcp-server             @memofs/core SDK
   (SessionStart / Compaction)        (memofs.context / remember)    (memo.context() / writeMemory())
               │                             │                              │
               └─────────────────────────────┼──────────────────────────────┘
                                             │
                                             ▼
                                  .memofs/ Memory Store
                            (core.md, notes.md, recall index)

Zero-Touch Hooks Mode (Claude Code, OpenAI Codex, OpenCode): Automatically injects project context at session startup, propagates memory to subagents, and re-injects memory after context compaction.
MCP Server Mode (Cursor, GitHub Copilot, Windsurf, Gemini CLI): Connects via the Model Context Protocol, exposing standard memory tools (memofs.context, memofs.remember, memofs.recall).
Programmatic Core SDK Mode (Custom Agent Frameworks & Runtimes): Direct TypeScript SDK (@memofs/core) for agent engineers embedding memory natively into autonomous agent loops.

Step 1: Initialize MemoFS in Your Repository

From the root of your project directory, run:

# Install the CLI globally or as a dev dependency
npm install -g @memofs/cli

# Initialize the .memofs/ memory runtime directory
npx memofs init

This creates the .memofs/ directory containing your core briefing file (.memofs/memory/core.md), long-term notes (.memofs/memory/notes.md), derived search indexes, and entity graph files.

Step 2: Configure Your Specific Agent or Runtime

Option A: Claude Code & OpenAI Codex (Automatic Zero-Touch Hooks)

Generate the agent configuration and hook scripts with a single command:

# Claude code
npx memofs generate agent claude --project-name "My Application"

# Codex
npx memofs generate agent codex --project-name "My Application" --scope local

What this configures automatically:

Session Start Hook: When you launch claude or codex, MemoFS queries your local memory store and injects a compact briefing (~6 KB) directly into the agent's initial prompt.
Subagent Hook: When your main agent spawns subagents, the subagents automatically inherit the parent session's memory context.
Compaction-Survival Hook: When the agent compacts its context window, MemoFS intercepts the event and re-injects core project rules—preventing memory loss during long sessions.
Session End Summary: Outputs a quick compliance summary of memories accessed and persisted during the session.

Option B: Cursor IDE (via MCP)

To wire MemoFS rules and MCP configuration into Cursor:

npx memofs generate agent cursor

This generates .cursor/rules/memofs.mdc and registers the MemoFS MCP server in .cursor/mcp.json:

{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}

Now Cursor can natively invoke memofs.context at the start of composer tasks and call memofs.remember whenever you instruct it to save a decision.

Option C: GitHub Copilot / VS Code

To configure VS Code and Copilot instructions and MCP server:

npx memofs generate agent copilot

This creates .vscode/mcp.json and adds memory management instructions to .github/copilot-instructions.md.

Option C: Any other coding agent that speak MCP

Checkout our cookbooks

Option E: Custom Agent Runtimes & Frameworks (via `@memofs/core` SDK)

If you are building custom AI agents in Node.js or TypeScript, install @memofs/core directly:

npm install @memofs/core

Instantiate the MemoFS engine inside your agent loop to fetch task-aware context briefings and persist learned facts:

import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

const memo = new MemoFS({
  store: createNodeFsMemoryStore({ rootDir: "." }),
  projectId: "custom-agent-app",
  mode: "local",
});

// Fetch system prompt briefing for custom LLM call
const ctx = await memo.context({ query: "Refactor payment service", taskType: "refactor" });
console.log(ctx.text)

// Save decisions programmatically
await memo.writeMemory({ content: "Payment service uses Stripe v3 API", kind: "decision" });

Step 3: Record Memories & Test Context Persistence

Recording Memories via CLI

You can explicitly record project rules, architectural decisions, and stack constraints directly from your terminal:

# Record an architectural decision
npx memofs remember "We use PostgreSQL with Drizzle ORM for main storage, and Redis for session cache" --kind decision

# Record a technical constraint
npx memofs remember "Do not use Axios. All HTTP requests must use native fetch with custom retry wrappers" --kind constraint

Automatic Memory Extraction During Agent Sessions

When working with your agent, instruct it naturally or let it decide when to remember relevant things:

You: "We just refactored the auth module to use Argon2id instead of bcrypt. Remember this decision in MemoFS."

Agent: Calls memofs.remember("Auth password hashing uses Argon2id", { kind: "decision" }) or memo.writeMemory().

MemoFS: Sanitizes secrets, tags frontmatter metadata, and writes the record to .memofs/memory/notes.md.

Step 4: Verify Memory Health with `memofs doctor`

MemoFS includes a built-in diagnostic tool to verify store integrity, validate frontmatter schemas, and rebuild derived search indexes:

npx memofs doctor

MemoFS doctor passed.

Summary of Agent Support Matrix

Agent Tool / Framework	Integration Mode	Context Auto-Load	Compaction Survival	Integration Method
Claude Code	Native Hooks	✅ Automatic	✅ Automatic	`npx memofs generate agent claude`
OpenAI Codex	Native Hooks	✅ Automatic	✅ Automatic	`npx memofs generate agent codex`
OpenCode	Plugin Hooks	✅ Plugin-assisted	✅ Session toast	`npx memofs generate agent opencode`
Cursor	MCP Server	💡 Via MDC Rule	💡 Rule-guided	`npx memofs generate agent cursor`
AGENTS.md supported agents	MCP Server	💡 Via Rules	💡 Rule-guided	`npx memofs generate agent-rules agents`
GitHub Copilot	MCP Server	💡 Instructions file	💡 Instruction-guided	`npx memofs generate agent copilot`
Custom TS Runtimes	Core SDK	✅ Programmatic	✅ Programmatic	`npm install @memofs/core`

Next Steps & Further Reading

Why AI Agents Lose Their Memory And How MemoFS Solves It

Christopher S. Aondona — Thu, 30 Jul 2026 18:50:09 +0000

Whether you are using off-the-shelf AI coding tools like Claude Code and Cursor or building custom autonomous AI agents with TypeScript and LLM APIs, you hit the exact same fundamental wall: AI agent amnesia.

As an agent user, you spend forty-five minutes explaining your architecture, deployment quirks, and database rules. The agent writes brilliant code. You close the CLI or tab, open a new session the next morning, and the agent suggests the exact legacy library you rejected yesterday.

As an agent builder, you struggle to keep your custom agentic loops focused. As multi-step agent trajectories expand, LLM token limits force context compaction, wiping out subtle rules and past decisions while escalating API costs.

The intelligence is real. The amnesia is structural.

Context Windows Are Working Memory, Not Long-Term Memory

The AI industry’s standard reflex to agent amnesia has been pushing context windows to 1M+ tokens. But a context window is working memory (RAM), not long-term storage (disk).

Relying on massive context windows introduces three critical engineering bottlenecks for both users and builders:

Context Compaction Destroys Rationale: When a session reaches token limits, agents automatically compact their context history. Compaction summarizes conversations into short summaries, quietly wiping out subtle architectural constraints, edge cases, and past decisions.
Context Drift & Attention Loss: LLMs struggle with needle-in-a-haystack attention degradation when context windows are stuffed with 100k+ lines of raw conversation history.
Escalating API Costs & Latency: Re-sending full project transcripts on every prompt burns tokens rapidly and adds seconds of input processing delay for users while skyrocketing LLM bills for agent builders.

Agents do not need larger transcripts. They need a durable, inspectable, versioned memory layer.

Why Vector Databases Fall Short for Local & Workspace Agent Workflows

When developers and AI engineers realize raw context windows aren't enough, the second reflex is to deploy a vector database. While vector search is excellent for passage retrieval in static documentation, it creates major friction when used for coding agents and local agent runtimes:

Opaque Blob Stores: You cannot cat or grep a vector database. When an agent acts on incorrect memory, neither the user nor the framework builder can easily inspect, diff, or debug what it remembered.
No Native Version Control: Vector databases live outside your codebase. They do not track git branches, commits, or pull requests.
Keyword & Exact Match Failure: Cosine similarity is famously unreliable for exact symbol names, error codes, file paths, and temporal questions ("what replaced our auth middleware last Tuesday?").

The MemoFS Solution: File-First Memory Runtimes

MemoFS is built on a fundamental insight: plain files are the optimal storage primitive for AI agent memory.

Instead of hiding memory inside remote databases or proprietary dashboards, MemoFS stores all agent memories as plain, structured Markdown and JSON directly within your project's .memofs/ directory.

The 6 Memory Layers of `.memofs/`

.memofs/
├── memory/
│   ├── core.md            # Always-on briefing (project rules, stack, active constraints)
│   └── notes.md           # Long-form durable records (decisions, summaries, rationale)
├── events/
│   ├── memory-events.jsonl# Append-only audit trail of all memory writes
│   └── conversations.jsonl# Session interaction logs
├── indexes/
│   ├── chunks.jsonl       # Tokenized text chunks
│   └── embeddings.jsonl   # Derived local vector index (BM25 + vector hybrid)
├── graph/
│   ├── nodes.jsonl        # Entities & concepts
│   └── edges.jsonl        # Relationships & supersedes links
└── snapshots/
    └── snapshots.jsonl    # Versioned checkpoints for instant rollback

6 Engineering Disciplines Behind MemoFS

MemoFS transforms plain files into an intelligent memory engine through six structural disciplines:

1. Canonical Storage vs. Disposable Indexes

In MemoFS, markdown and JSON files under .memofs/ are the single source of truth. The full-text index, vector embeddings, and entity graph are derived artifacts. If an index is corrupted or an embedding model changes, running npx memofs doctor instantly rebuilds the entire search layer from raw files with zero data loss.

2. Write-Time Intelligence & Secret Rejection

Memory quality is determined at write time. Before any memory lands on disk, MemoFS executes:

Secret & PII Filtering: Regex blocklists scan and reject API keys (sk-...), credentials, and tokens up front.
Durability Classification: A zero-config classifier separates long-term architectural facts (durable) from single-session task state (transient). Only durable memories are indexed for long-term recall.

3. Solving Memory Staleness with `supersedes` Graph Edges

When project requirements change, old memories become stale. Deleting them loses context; keeping them creates contradictions. MemoFS links updated memories to older records using supersedes graph edges. When queried, the engine surfaces the current rule while keeping the historical decision chain intact.

4. Zero-Key Hybrid Recall

MemoFS fuses three search signals for every query:

Score = w_{1} \cdot BM25 + w_{2} \cdot FuzzyMatch + w_{3} \cdot VectorSimilarity

Out of the box, local mode operates completely offline with zero API keys using lexical BM25 and fuzzy string matching. When enabled, local ONNX embeddings upgrade the system to full hybrid recall without cloud dependencies.

5. Multi-Interface Access: Hooks, MCP & Core SDK

MemoFS connects to agents through three complementary mechanisms to serve both end users and agent builders:

Lifecycle Hooks (For Agent Users): Auto-injects context at session start and re-injects context after compaction for CLI tools like Claude Code and OpenAI Codex.
Model Context Protocol (MCP) (For IDE Users & MCP Agents): Exposes standard tools (memofs.context, memofs.remember) for Cursor, Copilot, Windsurf, and Gemini CLI.
Programmatic TypeScript SDK (For Agent Builders): @memofs/core provides direct TypeScript APIs (memo.context(), memo.writeMemory()) for custom agent loops and autonomous multi-agent systems.

6. Forensic Auditability & Security

Because memory lives in git-tracked text files, every memory write is diffable, reviewable in pull requests, and forensically traceable. If an untrusted source attempts memory poisoning, developers can run git diff .memofs/ to inspect and revert the change instantly.

Getting Started: For Agent Users & Agent Builders

For Agent Users (CLI & IDE Setup in 2 Minutes)

# 1. Install MemoFS CLI
npm install -g @memofs/cli

# 2. Initialize .memofs/ in your repository
npx memofs init

# 3. Generate hooks / MCP config for your agent
npx memofs generate agent claude --project-name "My App"
# or Codex
npx memofs generate agent codex --project-name "My App" --scope local
#or for Cursor / Copilot / IDEs, e.t.c:
npx memofs generate agent cursor

For Agent Builders (Programmatic `@memofs/core` SDK)

import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

// Initialize durable workspace memory in your agent framework
const memo = new MemoFS({
  store: createNodeFsMemoryStore({ rootDir: "." }),
  projectId: "custom-agent",
  mode: "local",
});

// Inject task-aware memory briefing into system prompt
const context = await memo.context({ query: userTask, taskType: "coding" });
console.log(context.text);

// Persist facts learned during execution
await memo.writeMemory({ content: "Auth uses JWT with Argon2id", kind: "decision" });

Explore Further

Official Open-Source Documentation: https://docs.memofs.dev
Deep Architecture Essay: Read the full architecture breakdown
GitHub Repository: https://github.com/memo-fs/memofs

Building MemoFS

Christopher S. Aondona — Tue, 14 Jul 2026 10:52:39 +0000

I am using MemoFS in MemoFS to build MemoFS

Reciprocal Rerank Fusion (RRF): The Simple, Powerful Way to Combine Keyword + Semantic Search in RAG

Christopher S. Aondona — Tue, 14 Jul 2026 10:01:34 +0000

If you've built a RAG application, you’ve probably hit this wall:

Keyword search (Best Match 25 [BM25]) is great at exact matches.
Vector search captures semantic meaning.
But combining the two ranked lists is painful because their scores live on completely different scales.

Manually normalizing scores is fragile. Reciprocal Rank Fusion (RRF) solves this elegantly by ignoring raw scores entirely and only looking at rank positions.

RRF has become the standard fusion method in MemoFS, Elasticsearch, OpenSearch, Azure AI Search, Weaviate, MongoDB Atlas, and modern RAG pipelines.

In this post, I’ll show you exactly how RRF works and give you clean, production-ready TypeScript implementations.

How RRF Works

RRF assigns a score to each document using this simple formula:

RRF (d) = r \in R \sum \frac{1}{k + rank _{r} ( d )}

Where:

$d$ = document
$R$ = list of ranked result sets
$rank_{r} (d)$ = position of the document in that result set (starting at 1)
$k$ = smoothing constant (default: 60)

Documents are then sorted by their final RRF score (highest first).

TypeScript Implementation

Here’s a clean, generic, and reusable TypeScript version:

/**
 * Reciprocal Rank Fusion (RRF)
 * Fuses multiple ranked lists into a single ranked list
 */
export function reciprocalRankFusion<T>(
  rankedLists: T[][],
  options: {
    k?: number;      // Smoothing constant (default: 60)
    topK?: number;   // Limit number of results returned
  } = {}
): Array<{ item: T; score: number }> {
  const { k = 60, topK } = options;
  const rrfScores = new Map<T, number>();

  for (const rankedList of rankedLists) {
    rankedList.forEach((item, index) => {
      const rank = index + 1;
      const currentScore = rrfScores.get(item) ?? 0;
      rrfScores.set(item, currentScore + 1 / (k + rank));
    });
  }

  // Convert to array and sort by score (descending)
  let results = Array.from(rrfScores.entries()).map(([item, score]) => ({
    item,
    score,
  }));

  results.sort((a, b) => b.score - a.score);

  if (topK !== undefined) {
    results = results.slice(0, topK);
  }

  return results;
}

Usage example:

const bm25Results = ["doc_B", "doc_A", "doc_D", "doc_C"];
const vectorResults = ["doc_B", "doc_E", "doc_A", "doc_F"];

const fusedResults = reciprocalRankFusion([bm25Results, vectorResults], {
  k: 60,
  topK: 10,
});

console.log(fusedResults);
// [
//   { item: 'doc_B', score: 0.03125 },
//   { item: 'doc_A', score: 0.02548 },
//   ...
// ]

Note: This implementation works best when items are primitives (string, number) or the same object references. For complex objects, consider using document IDs or a Map with string keys.

Working with LangChain.js

You can easily integrate RRF into LangChain.js workflows. Here’s a practical pattern:

import { EnsembleRetriever } from "langchain/retrievers/ensemble"; // or implement manually
import { BM25Retriever } from "@langchain/community/retrievers/bm25";
import { VectorStoreRetriever } from "langchain/vectorstores/base";

// Example: Combine BM25 + Vector retriever
const bm25Retriever = BM25Retriever.fromDocuments(docs);
const vectorRetriever = vectorStore.asRetriever({ k: 20 });

const ensembleRetriever = new EnsembleRetriever({
  retrievers: [bm25Retriever, vectorRetriever],
  weights: [0.5, 0.5],
  // Internally uses weighted RRF
});

const results = await ensembleRetriever.invoke("your query");

If you prefer full control, just use the reciprocalRankFusion function above after fetching results from multiple retrievers.
MemoFS handles this automatically for you out of the box.

Why RRF is So Effective

No score normalization required
Rewards documents that rank well across multiple methods
Extremely robust (proven in the original 2009 SIGIR paper)
Only one parameter (k), and 60 works great in most cases

Best Practices in TypeScript Projects

Fetch more candidates than you need (k: 20–50 per retriever)
Fuse and then take the top 5–10 results
Use document IDs when working with objects
Consider adding light weighting when one retrieval method is consistently stronger

Are you a developer using coding agents, building RAG systems, or implementing AI memories?

Check out the full documentation and ready-to-use AI agents/apps memory at:

https://docs.memofs.dev

Whether you're deploying to a Node environment or Cloudflare workers, you'll find practical guides to take your retrieval quality to the next level.

What’s your current approach to hybrid search? Are you still normalizing scores, or have you switched to RRF? Let me know in the comments!

Token Jaccard Similarity in TypeScript: Simple Text Comparison

Christopher S. Aondona — Tue, 14 Jul 2026 09:21:46 +0000

Hey TypeScript devs! 👋

If you need a fast, lightweight way to measure how similar two pieces of text are (duplicate detection, content recommendations, search result grouping, or data cleaning), Token Jaccard Similarity is an excellent choice.

It’s simple to understand, works great in both browser and Node.js, and requires zero dependencies.

What is Jaccard Similarity?

The Jaccard index measures similarity between two sets:

J (A, B) = \frac{∣ A \cap B ∣}{∣ A \cup B ∣}

Intersection = tokens present in both texts
Union = all unique tokens from either text

Result ranges from 0 (completely different) to 1 (identical).

Token Jaccard = Jaccard applied to words

We tokenize the text into words, convert them into Sets (removing duplicates and order), then apply the formula.

Quick Example

Text A:

the quick brown fox jumps over the lazy dog

Text B:

a quick brown fox jumps over a lazy dog

Unique tokens:

Text A: the, quick, brown, fox, jumps, over, lazy, dog
Text B: a, quick, brown, fox, jumps, over, lazy, dog

Intersection: 7 tokens

Union: 9 tokens

Jaccard Similarity ≈ 0.78 (78% similar)

TypeScript Implementation

Here’s a clean, fully typed implementation:

function tokenize(text: string): Set<string> {
  // Matches words (alphanumeric), lowercased
  const matches = text.toLowerCase().match(/\b\w+\b/g);
  return new Set(matches ?? []);
}

function jaccardSimilarity(text1: string, text2: string): number {
  const set1 = tokenize(text1);
  const set2 = tokenize(text2);

  if (set1.size === 0 && set2.size === 0) {
    return 1;
  }

  // Calculate intersection size
  let intersectionSize = 0;
  for (const token of set1) {
    if (set2.has(token)) {
      intersectionSize++;
    }
  }

  const unionSize = set1.size + set2.size - intersectionSize;

  return intersectionSize / unionSize;
}

// ======================
// Example usage
// ======================

const textA = "the quick brown fox jumps over the lazy dog";
const textB = "a quick brown fox jumps over a lazy dog";

const score = jaccardSimilarity(textA, textB);
console.log(`Jaccard Similarity: ${score.toFixed(4)}`); 
// → Jaccard Similarity: 0.7778

Another Example

const textC = "Building a recommendation system using TypeScript and machine learning";
const textD = "How to create a recommendation engine with TypeScript and ML";

console.log(jaccardSimilarity(textC, textD).toFixed(2)); 
// → 0.50

Real-World Use Cases

Use Case	Why It Works Well in TypeScript	Suggested Threshold
Duplicate content detection	Extremely fast even on large datasets	> 0.85
Article / blog recommendations	Good for topic similarity	0.4 – 0.65
Dataset deduplication	Lightweight preprocessing step	> 0.90
Search result clustering	Quick fuzzy grouping	> 0.70
Basic plagiarism detection	Simple and explainable baseline	> 0.60

Limitations & Quick Improvements

Token Jaccard is great but has trade-offs:

Ignores word order and semantics
Sensitive to common words (“the”, “a”, “is”)

Easy Upgrades

Remove stop words before tokenizing
Use n-grams (word or character shingles) instead of single words
Combine with other metrics (e.g. cosine similarity on embeddings)

But for most practical needs, plain Token Jaccard in TypeScript is already very effective and blazing fast.

When to Use It

You want something simple and dependency-free
You’re working in TypeScript / JavaScript (frontend, backend, or full-stack)
You need explainable results
You’re building a quick prototype or data pipeline

Conclusion

Token Jaccard Similarity remains one of the most practical tools for text comparison. With this TypeScript version, you can drop it into any project instantly — browser, Node.js, Deno, or even Edge functions.

Would you like me to show:

A version with stop-word removal?
N-gram (shingle) based Jaccard?
How to use it efficiently at scale?

Just let me know in the comments!

The Markdown File That Beat a $50M Vector Database: Separating Storage and Search in Agent Memory

Christopher S. Aondona — Wed, 01 Jul 2026 21:28:37 +0000

In the rush to build AI agents, we defaulted to complex vector databases. But high-traffic platforms are converging on a simpler, more robust foundation: plain files.

Most long-term agent memory setups are massively over-engineered.

When developers start building LLM applications, the default prescription is almost always: "Spin up a managed vector database and build a RAG pipeline."

But if you look at the highest-traffic production agent platforms (like Claude Code, Manus, and OpenClaw), a quieter trend has emerged. They are bypassing the enterprise embeddings store and using plain markdown files as their primary memory substrate.

This is not a regression to simplicity. Done well, it is a stronger engineering foundation because files are inspectable, diffable, portable, and git-native.

But a folder of plain text notes with no structure is just a slow, poorly indexing database. To make a file-first architecture work at scale, you must follow a fundamental system design principle: separate storage from search.

The Core Invariant: Storage vs. Search

The single highest-leverage decision you can make in agent memory design is treating your storage layer and search indexes as completely separate systems.

Storage (Canonical Source of Truth): Versioned, human-readable files (Markdown + YAML frontmatter).
Search (Derived Index): Derived search structures (vector databases, full-text BM25 indexes, entity graphs, keyword indexes).

In this architecture, every search index is treated as a disposable artifact. You can delete your vector embeddings database or rebuild your entity graph at any time, with zero loss of underlying memory.

This buys you three advantages:

Auditability for free: By storing memories in text files, you can version-control them using Git. Every memory update, supersession, or correction is diffable, attributable, and reversible without any custom database versioning logic.
Algorithmic freedom: Swap your embedding models, adjust your chunking strategies, or change your ranking algorithms dynamically. You just rebuild the index from your markdown files. Your core data is never locked in.
Portability: Your memory store is completely decoupled from any specific vendor's database format. Migrating runtimes is a file copy (cp), not a database migration project.

Write-Path Intelligence: Structuring Memories

Retrieval quality is downstream of write quality. A system with simple retrieval over clean, structured memory consistently outperforms a complex RAG pipeline over noisy memory.

To achieve this, every memory unit must be structured at write time. A typical memory file in a file-first runtime looks like this:

---
id: mem_7c10e3
created: 2026-07-02T16:40:00Z
source: user_message
durability: durable
confidence: high
tags: [preference, deployment]
entities: [tekmemo, staging-env]
supersedes: mem_4f2a91
---
User now prefers staging deploys on any weekday, since the team added
automated rollback and no longer needs the Friday buffer.

By enforcing a structured frontmatter schema:

Atomicity: One memory file encodes exactly one fact or preference. This makes deduplication and conflict resolution precise.
Metadata Tracking: Source, timestamp, confidence, and entities are written immediately, rather than trying to infer them from raw text during reads.
Audit Trail: Notice the supersedes key. If a user's preference changes, we never edit a file in place. We write a new file and link it to the old one. The older file is excluded from the active search index but remains in the Git history, keeping the audit trail fully intact.

Making the Search Index Disposable

Because storage is safe on disk, your retrieval layer can be tuned aggressively. Instead of relying on raw vector similarity alone (which struggles with exact keyword match and temporal queries), you can build a disposable hybrid index.

A robust read-path uses Multi-Signal Fusion:

Semantic Search: A vector index mapping the text body.
Keyword Search: A BM25 index matching exact tokens.
Entity Match: A lightweight index mapping the entities array.

Using Reciprocal Rank Fusion (RRF), you combine these three signals into a unified rank list:

RRF_Score(d) = the sum of 1 / (k + rank of document d in each retrieval method).

Where the rank is the position of document d in a particular retrieval method, and k is a constant (usually 60). This avoids the scale-incompatibility problem of averaging a cosine similarity score directly against a BM25 score.

The Real-World Tradeoffs

An honest architecture must address its limits. The two main challenges of file-first memory are:

1. Concurrency

Files are a great source of truth for a single writer. They become a liability when multiple agents or parallel processes try to write concurrently.

Solution: For single-user environments, simple advisory file locking is enough. For multi-agent distributed systems, place a thin transactional gatekeeper (like SQLite) in front of the file writes to arbitrate concurrency, keeping the files themselves as the canonical backup.

2. Memory Poisoning (MINJA)

If your agent can read untrusted external sources (web pages, third-party emails), an attacker can inject malicious text designed to get indexed as "durable memory." Future queries retrieve this poisoned record, hijacking the agent's behavior.

Solution: The source tag is critical. Untrusted sources must write memories with low-confidence tags and route through a trust-threshold classifier before being allowed into the main search index.

Introducing TekMemo

This is the exact problem we are solving with tekmemo. We are building a production-ready, file-first long-term memory runtime for AI agents that handles write-path intelligence, multi-signal fusion, and automatic git-native auditing out of the box.

We are launching soon. If you want to build durable, auditable, and resilient agent memories without spinning up complex external vector databases, stay tuned for our upcoming launch.

Build a Full-Stack Todo App with React & Node.js - The Complete Walkthrough

Christopher S. Aondona — Sat, 24 Jan 2026 18:40:36 +0000

You've probably built a todo app before. Maybe five times.

But have you ever really understood every line you wrote?

Today we're building one more. But differently.

At every step, I'll ask you questions. Try to answer them before scrolling. This is how you actually learn—active recall beats passive reading every time.

What We're Building

A full-stack todo app with:

React frontend with hooks
Express.js REST API
In-memory storage (for simplicity)
Full CRUD operations

By the end, you'll understand:

How useState and useEffect really work
REST API design patterns
Frontend-backend communication
Error handling strategies

Step 1: Project Setup

mkdir fullstack-todo && cd fullstack-todo
mkdir client server

🤔 Before we continue...

Question 1: Why are we separating client and server into different folders? What's the alternative, and when would you use it?

Think about it for 30 seconds before continuing.

The answer: Separation of concerns. We could use a monolithic approach (like Next.js), but separate folders give us deployment flexibility and clearer mental models.

Step 2: Backend Setup

cd server
npm init -y
npm pkg set type="module"
npm install express cors

Create server/index.js:

import express from 'express';
import cors from 'cors';

const app = express();
app.use(cors());
app.use(express.json());

let todos = [];
let nextId = 1;

// GET all todos
app.get('/api/todos', (req, res) => {
  res.json(todos);
});

// POST new todo
app.post('/api/todos', (req, res) => {
  const { title } = req.body;
  const todo = { id: nextId++, title, completed: false };
  todos.push(todo);
  res.status(201).json(todo);
});

// PATCH toggle completion
app.patch('/api/todos/:id', (req, res) => {
  const todo = todos.find(t => t.id === parseInt(req.params.id));
  if (!todo) return res.status(404).json({ error: 'Todo not found' });
  todo.completed = !todo.completed;
  res.json(todo);
});

// DELETE todo
app.delete('/api/todos/:id', (req, res) => {
  const index = todos.findIndex(t => t.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'Todo not found' });
  todos.splice(index, 1);
  res.status(204).send();
});

app.listen(3001, () => console.log('Server running on port 3001'));

🤔 Stop and think...

Question 2: Why did we use 201 for POST and 204 for DELETE? What's the difference, and why does it matter?

Question 3: There's a bug in this code that would break in production. Can you spot it?

Hints:

What happens when the server restarts?
What happens if two users add todos simultaneously?

Step 3: Frontend Setup

cd ../client
npm create vite@latest . -- --template react
npm install

Replace src/App.jsx:

import { useState, useEffect } from 'react';
import './App.css';

const API_URL = 'http://localhost:3001/api/todos';

function App() {
  const [todos, setTodos] = useState([]);
  const [newTodo, setNewTodo] = useState('');
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetchTodos();
  }, []);

  async function fetchTodos() {
    try {
      setLoading(true);
      const res = await fetch(API_URL);
      if (!res.ok) throw new Error('Failed to fetch');
      const data = await res.json();
      setTodos(data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  async function addTodo(e) {
    e.preventDefault();
    if (!newTodo.trim()) return;

    try {
      const res = await fetch(API_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ title: newTodo }),
      });
      const todo = await res.json();
      setTodos([...todos, todo]);
      setNewTodo('');
    } catch (err) {
      setError('Failed to add todo');
    }
  }

  async function toggleTodo(id) {
    try {
      const res = await fetch(`${API_URL}/${id}`, { method: 'PATCH' });
      const updated = await res.json();
      setTodos(todos.map(t => t.id === id ? updated : t));
    } catch (err) {
      setError('Failed to update todo');
    }
  }

  async function deleteTodo(id) {
    try {
      await fetch(`${API_URL}/${id}`, { method: 'DELETE' });
      setTodos(todos.filter(t => t.id !== id));
    } catch (err) {
      setError('Failed to delete todo');
    }
  }

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div className="app">
      <h1>My Todos</h1>

      <form onSubmit={addTodo}>
        <input
          value={newTodo}
          onChange={e => setNewTodo(e.target.value)}
          placeholder="Add a new todo..."
        />
        <button type="submit">Add</button>
      </form>

      <ul>
        {todos.map(todo => (
          <li key={todo.id}>
            <span 
              onClick={() => toggleTodo(todo.id)}
              style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}
            >
              {todo.title}
            </span>
            <button onClick={() => deleteTodo(todo.id)}>Delete</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default App;

🤔 Understanding check...

Question 4: Why do we spread [...todos, todo] instead of todos.push(todo)? What would happen if we used push?

Question 5: The useEffect has an empty dependency array []. What does this mean? What would happen if we removed it entirely?

Step 4: Run It

Terminal 1:

cd server && node index.js

Terminal 2:

cd client && npm run dev

Visit http://localhost:5173 and test your app!

Challenges For You

If you really want to learn, try these without looking up the answers:

Add persistence - Save todos to a JSON file
Add validation - Prevent empty titles, limit title length
Add optimistic updates - Update UI before server confirms
Add filters - Show all/active/completed todos

What We Just Learned

REST API design patterns
React state management with hooks
Async/await with error handling
Frontend-backend separation

But here's the thing...

Did those questions help?

That active recall approach—stopping to think before seeing the answer—is proven to improve retention by 50% compared to passive reading.

Now imagine if you had an AI companion that could:

Ask you these questions in real-time
Adapt to YOUR specific confusion points
Review YOUR actual code, not generic examples
Remember what you've learned across projects

That's exactly what we're building at TekBreed.

Interactive tutorials and courses with AI that makes learning stick.

👉 Join the waitlist at tekbreed.com

What concept from this tutorial did you find most challenging? Drop a comment below!

Mastering JavaScript's URL() and URLSearchParams: A Complete Guide

Christopher S. Aondona — Tue, 28 Oct 2025 01:14:42 +0000

Introduction

Working with URLs in JavaScript used to be a messy affair involving string manipulation, regular expressions, and brittle parsing logic. The modern URL() and URLSearchParams APIs changed everything, providing robust, standardized interfaces for URL manipulation that solve countless headaches developers face daily.

In this comprehensive guide, we'll explore these APIs in depth, understanding not just how they work, but why they exist and the specific problems they solve.

The URL() Constructor: Understanding Web Addresses

What is URL()?

The URL() constructor creates URL objects that represent and parse Uniform Resource Locators. It takes a URL string (and optionally a base URL) and returns an object with properties representing each component of the URL.

Basic Syntax

new URL(url)
new URL(url, base)

Parameters:

url (required): An absolute or relative URL string
base (optional): A base URL string to resolve relative URLs against

Anatomy of a URL Object

When you create a URL object, it automatically parses the URL into its constituent parts:

const url = new URL('https://john:secret@example.com:8080/path/to/page?name=John&age=30#section');

console.log(url.href);       // "https://john:secret@example.com:8080/path/to/page?name=John&age=30#section"
console.log(url.protocol);   // "https:"
console.log(url.username);   // "john"
console.log(url.password);   // "secret"
console.log(url.host);       // "example.com:8080"
console.log(url.hostname);   // "example.com"
console.log(url.port);       // "8080"
console.log(url.pathname);   // "/path/to/page"
console.log(url.search);     // "?name=John&age=30"
console.log(url.hash);       // "#section"
console.log(url.origin);     // "https://example.com:8080"

Key Properties Explained

1. href - The complete URL string. This is both readable and writable:

const url = new URL('https://example.com/page');
url.href = 'https://newsite.com/newpage';
console.log(url.hostname); // "newsite.com"

2. protocol - The scheme of the URL (always includes the colon):

const url = new URL('https://example.com');
url.protocol = 'http:';
console.log(url.href); // "http://example.com"

3. username and password - Credentials in the URL (rarely used in modern web development due to security concerns):

const url = new URL('https://example.com');
url.username = 'admin';
url.password = 'pass123';
console.log(url.href); // "https://admin:pass123@example.com"

4. host vs hostname - A critical distinction:

host includes the port number
hostname is just the domain name

const url = new URL('https://example.com:3000');
console.log(url.host);     // "example.com:3000"
console.log(url.hostname); // "example.com"

5. port - The port number as a string (empty string if using default port):

const url = new URL('https://example.com:8080');
console.log(url.port); // "8080"

const url2 = new URL('https://example.com');
console.log(url2.port); // "" (empty string, not "443")

6. pathname - The path section, always starting with /:

const url = new URL('https://example.com/users/123/profile');
console.log(url.pathname); // "/users/123/profile"

url.pathname = '/posts/456';
console.log(url.href); // "https://example.com/posts/456"

7. search - The query string including the ?:

const url = new URL('https://example.com?foo=bar&baz=qux');
console.log(url.search); // "?foo=bar&baz=qux"

8. hash - The fragment identifier including the #:

const url = new URL('https://example.com/page#section-2');
console.log(url.hash); // "#section-2"

9. origin - Read-only property combining protocol, hostname, and port:

const url = new URL('https://example.com:8080/path?query');
console.log(url.origin); // "https://example.com:8080"

Working with Relative URLs

One of the most powerful features of URL() is resolving relative URLs against a base:

// Resolving relative paths
const base = 'https://example.com/users/123/profile';

const url1 = new URL('edit', base);
console.log(url1.href); // "https://example.com/users/123/edit"

const url2 = new URL('../456/posts', base);
console.log(url2.href); // "https://example.com/users/456/posts"

const url3 = new URL('/api/data', base);
console.log(url3.href); // "https://example.com/api/data"

const url4 = new URL('?page=2', base);
console.log(url4.href); // "https://example.com/users/123/profile?page=2"

Key Methods of URL

1. toString() - Returns the complete URL as a string (equivalent to href):

const url = new URL('https://example.com/page');
console.log(url.toString()); // "https://example.com/page"
console.log(String(url));    // "https://example.com/page"

2. toJSON() - Returns the URL string for JSON serialization:

const url = new URL('https://example.com/api');
console.log(JSON.stringify({ endpoint: url })); 
// {"endpoint":"https://example.com/api"}

Static Methods

URL.canParse(url, base) - Check if a URL is valid without throwing an error (modern browsers):

console.log(URL.canParse('https://example.com')); // true
console.log(URL.canParse('not a url'));           // false
console.log(URL.canParse('/relative', 'https://example.com')); // true

URL.createObjectURL(blob) - Creates a temporary URL for Blob or File objects:

const blob = new Blob(['Hello'], { type: 'text/plain' });
const blobUrl = URL.createObjectURL(blob);
console.log(blobUrl); // "blob:https://example.com/550e8400-e29b-41d4-a716-446655440000"

// Don't forget to revoke when done
URL.revokeObjectURL(blobUrl);

URLSearchParams: The Query String Swiss Army Knife

What is URLSearchParams?

URLSearchParams is an interface for working with query strings. It provides methods to read, add, modify, and delete query parameters without manual string manipulation.

Creating URLSearchParams

There are multiple ways to create a URLSearchParams object:

1. From a query string:

const params = new URLSearchParams('name=John&age=30&age=31');

2. From an object (modern approach):

const params = new URLSearchParams({
  name: 'John',
  age: 30,
  city: 'New York'
});

3. From an array of key-value pairs:

const params = new URLSearchParams([
  ['name', 'John'],
  ['age', '30'],
  ['hobby', 'coding'],
  ['hobby', 'reading']
]);

4. From a URL object's searchParams property:

const url = new URL('https://example.com?name=John&age=30');
const params = url.searchParams; // Direct reference, not a copy!

Core Methods: Reading Parameters

1. get(name) - Retrieves the first value for a parameter:

const params = new URLSearchParams('name=John&age=30&age=31');
console.log(params.get('name')); // "John"
console.log(params.get('age'));  // "30" (first value only)
console.log(params.get('city')); // null (doesn't exist)

2. getAll(name) - Retrieves all values for a parameter as an array:

const params = new URLSearchParams('tag=js&tag=web&tag=api');
console.log(params.getAll('tag')); // ["js", "web", "api"]
console.log(params.getAll('missing')); // [] (empty array)

3. has(name) - Checks if a parameter exists:

const params = new URLSearchParams('name=John&age=30');
console.log(params.has('name')); // true
console.log(params.has('city')); // false

4. keys() - Returns an iterator of all parameter names:

const params = new URLSearchParams('name=John&age=30&city=NYC');
for (const key of params.keys()) {
  console.log(key); // "name", "age", "city"
}

// Convert to array
console.log([...params.keys()]); // ["name", "age", "city"]

5. values() - Returns an iterator of all parameter values:

const params = new URLSearchParams('name=John&age=30');
for (const value of params.values()) {
  console.log(value); // "John", "30"
}

6. entries() - Returns an iterator of [key, value] pairs:

const params = new URLSearchParams('name=John&age=30');
for (const [key, value] of params.entries()) {
  console.log(`${key}: ${value}`);
  // "name: John"
  // "age: 30"
}

// URLSearchParams is directly iterable
for (const [key, value] of params) {
  console.log(`${key}: ${value}`);
}

7. forEach(callback) - Executes a callback for each parameter:

const params = new URLSearchParams('name=John&age=30');
params.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});

Core Methods: Modifying Parameters

1. set(name, value) - Sets a parameter, replacing all existing values:

const params = new URLSearchParams('name=John&age=30&age=31');
params.set('age', '25');
console.log(params.toString()); // "name=John&age=25"

params.set('city', 'NYC');
console.log(params.toString()); // "name=John&age=25&city=NYC"

2. append(name, value) - Adds a parameter without removing existing ones:

const params = new URLSearchParams('tag=js');
params.append('tag', 'web');
params.append('tag', 'api');
console.log(params.toString()); // "tag=js&tag=web&tag=api"

3. delete(name) - Removes a parameter:

const params = new URLSearchParams('name=John&age=30&city=NYC');
params.delete('age');
console.log(params.toString()); // "name=John&city=NYC"

Modern delete() with value parameter:

const params = new URLSearchParams('tag=js&tag=web&tag=js');
params.delete('tag', 'js'); // Remove only 'tag=js' entries
console.log(params.toString()); // "tag=web"

4. sort() - Sorts parameters alphabetically by key:

const params = new URLSearchParams('zebra=1&apple=2&mango=3');
params.sort();
console.log(params.toString()); // "apple=2&mango=3&zebra=1"

5. toString() - Converts to query string (without leading ?):

const params = new URLSearchParams({ name: 'John', age: 30 });
console.log(params.toString()); // "name=John&age=30"
console.log('?' + params.toString()); // "?name=John&age=30"

Integration with URL

The real power emerges when combining URL and URLSearchParams:

const url = new URL('https://api.example.com/users');

// url.searchParams is a live URLSearchParams object
url.searchParams.set('page', '2');
url.searchParams.set('limit', '10');
url.searchParams.append('sort', 'name');

console.log(url.href); 
// "https://api.example.com/users?page=2&limit=10&sort=name"

// Modifications to searchParams immediately affect the URL
url.searchParams.delete('limit');
console.log(url.href); 
// "https://api.example.com/users?page=2&sort=name"

Real-World Problems They Solve

Problem 1: Safe Query String Parsing

Before URL APIs:

// Fragile and error-prone
function getQueryParam(url, param) {
  const regex = new RegExp('[?&]' + param + '=([^&#]*)');
  const results = regex.exec(url);
  return results ? decodeURIComponent(results[1]) : null;
}

// Doesn't handle multiple values, encoding issues, etc.

With URLSearchParams:

const url = new URL(window.location.href);
const paramValue = url.searchParams.get('param');
// Handles encoding, multiple values, and edge cases automatically

Problem 2: Building Dynamic API URLs

Before URL APIs:

// Manual string concatenation - prone to bugs
let apiUrl = 'https://api.example.com/search?';
if (query) apiUrl += 'q=' + encodeURIComponent(query) + '&';
if (page) apiUrl += 'page=' + page + '&';
if (filters) {
  filters.forEach(f => {
    apiUrl += 'filter=' + encodeURIComponent(f) + '&';
  });
}
apiUrl = apiUrl.slice(0, -1); // Remove trailing &

With URL APIs:

const apiUrl = new URL('https://api.example.com/search');
if (query) apiUrl.searchParams.set('q', query);
if (page) apiUrl.searchParams.set('page', page);
if (filters) {
  filters.forEach(f => apiUrl.searchParams.append('filter', f));
}
// Clean, readable, no encoding worries

Problem 3: URL Modification Without Reloading

Updating browser URL state:

// Update URL without page reload (for SPAs)
function updateFilters(filters) {
  const url = new URL(window.location);
  url.searchParams.delete('filter'); // Clear existing
  filters.forEach(f => url.searchParams.append('filter', f));

  window.history.pushState({}, '', url);
}

Problem 4: Handling Complex Query Strings

Working with arrays and multiple values:

// Building a search URL with multiple filters
const searchUrl = new URL('https://shop.example.com/products');
searchUrl.searchParams.set('category', 'electronics');
searchUrl.searchParams.append('color', 'black');
searchUrl.searchParams.append('color', 'silver');
searchUrl.searchParams.set('minPrice', '100');
searchUrl.searchParams.set('maxPrice', '500');

console.log(searchUrl.href);
// "https://shop.example.com/products?category=electronics&color=black&color=silver&minPrice=100&maxPrice=500"

// Reading multiple values on the backend/client
const colors = searchUrl.searchParams.getAll('color');
console.log(colors); // ["black", "silver"]

Problem 5: Form Data to URL Query

Converting form data to URL query string:

const formData = new FormData(document.querySelector('form'));
const searchParams = new URLSearchParams(formData);

const apiUrl = new URL('https://api.example.com/submit');
apiUrl.search = searchParams.toString();

fetch(apiUrl)
  .then(response => response.json())
  .then(data => console.log(data));

Problem 6: URL Validation and Sanitization

Safely validating URLs:

function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch (err) {
    return false;
  }
}

console.log(isValidUrl('https://example.com')); // true
console.log(isValidUrl('not a url')); // false

// Or with modern browsers:
console.log(URL.canParse('https://example.com')); // true

Practical Examples

Example 1: Pagination Helper

class PaginationHelper {
  constructor(baseUrl) {
    this.url = new URL(baseUrl);
  }

  setPage(page) {
    this.url.searchParams.set('page', page);
    return this;
  }

  setLimit(limit) {
    this.url.searchParams.set('limit', limit);
    return this;
  }

  setSort(field, order = 'asc') {
    this.url.searchParams.set('sort', field);
    this.url.searchParams.set('order', order);
    return this;
  }

  getUrl() {
    return this.url.href;
  }
}

const pagination = new PaginationHelper('https://api.example.com/users');
const url = pagination
  .setPage(2)
  .setLimit(20)
  .setSort('name', 'desc')
  .getUrl();

console.log(url);
// "https://api.example.com/users?page=2&limit=20&sort=name&order=desc"

Example 2: Search Filter Manager

class SearchFilters {
  constructor(currentUrl = window.location.href) {
    this.url = new URL(currentUrl);
  }

  addFilter(key, value) {
    this.url.searchParams.append(key, value);
    return this;
  }

  removeFilter(key, value = null) {
    if (value === null) {
      this.url.searchParams.delete(key);
    } else {
      // Remove specific value
      const values = this.url.searchParams.getAll(key);
      this.url.searchParams.delete(key);
      values.filter(v => v !== value).forEach(v => {
        this.url.searchParams.append(key, v);
      });
    }
    return this;
  }

  getFilters(key) {
    return this.url.searchParams.getAll(key);
  }

  clearAll() {
    // Keep only specific params like page
    const page = this.url.searchParams.get('page');
    this.url.search = '';
    if (page) this.url.searchParams.set('page', page);
    return this;
  }

  apply() {
    window.history.pushState({}, '', this.url);
    // Trigger filter update event
    window.dispatchEvent(new CustomEvent('filtersChanged'));
  }

  toString() {
    return this.url.href;
  }
}

// Usage
const filters = new SearchFilters();
filters
  .addFilter('category', 'electronics')
  .addFilter('brand', 'apple')
  .addFilter('brand', 'samsung')
  .apply();

Example 3: API Client with Query Builder

class ApiClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
  }

  buildUrl(endpoint, params = {}) {
    const url = new URL(endpoint, this.baseUrl);

    Object.entries(params).forEach(([key, value]) => {
      if (Array.isArray(value)) {
        value.forEach(v => url.searchParams.append(key, v));
      } else if (value !== null && value !== undefined) {
        url.searchParams.set(key, value);
      }
    });

    return url.href;
  }

  async get(endpoint, params = {}) {
    const url = this.buildUrl(endpoint, params);
    const response = await fetch(url);
    return response.json();
  }
}

// Usage
const api = new ApiClient('https://api.example.com');

api.get('/products', {
  category: 'electronics',
  tags: ['new', 'featured'],
  minPrice: 100,
  maxPrice: 1000,
  page: 1
});
// Fetches: https://api.example.com/products?category=electronics&tags=new&tags=featured&minPrice=100&maxPrice=1000&page=1

Example 4: URL State Synchronizer

class UrlStateSync {
  constructor() {
    this.url = new URL(window.location);
    this.listeners = new Map();
  }

  setState(key, value) {
    if (value === null || value === undefined || value === '') {
      this.url.searchParams.delete(key);
    } else {
      this.url.searchParams.set(key, value);
    }

    this.updateUrl();
    this.notifyListeners(key, value);
  }

  getState(key) {
    return this.url.searchParams.get(key);
  }

  updateUrl() {
    window.history.replaceState({}, '', this.url);
  }

  onChange(key, callback) {
    if (!this.listeners.has(key)) {
      this.listeners.set(key, []);
    }
    this.listeners.get(key).push(callback);
  }

  notifyListeners(key, value) {
    if (this.listeners.has(key)) {
      this.listeners.get(key).forEach(callback => callback(value));
    }
  }
}

// Usage
const urlState = new UrlStateSync();

urlState.onChange('theme', (theme) => {
  document.body.className = theme;
});

urlState.setState('theme', 'dark'); // Updates URL and applies theme

Common Pitfalls and Best Practices

Pitfall 1: Forgetting URL Encoding

// ❌ Wrong - manual encoding issues
const url = 'https://api.example.com/search?q=' + query;

// ✅ Correct - automatic encoding
const url = new URL('https://api.example.com/search');
url.searchParams.set('q', query);

Pitfall 2: Modifying searchParams Reference

const url = new URL('https://example.com?name=John');

// url.searchParams is a live reference
const params = url.searchParams;
params.set('age', '30');

console.log(url.href); // Changed! "https://example.com?name=John&age=30"

// To get an independent copy:
const paramsCopy = new URLSearchParams(url.searchParams);

Pitfall 3: Using set() vs append()

const params = new URLSearchParams();

// set() replaces all values
params.set('tag', 'js');
params.set('tag', 'web');
console.log(params.toString()); // "tag=web" (only one)

// append() adds multiple values
params.append('tag', 'js');
params.append('tag', 'web');
console.log(params.toString()); // "tag=js&tag=web"

Best Practice 1: Always Validate URLs

function safeUrlParse(urlString, base) {
  try {
    return new URL(urlString, base);
  } catch (error) {
    console.error('Invalid URL:', urlString);
    return null;
  }
}

Best Practice 2: Use searchParams for Query Manipulation

// ❌ Avoid direct search manipulation
url.search = '?name=John&age=30';

// ✅ Use searchParams
url.searchParams.set('name', 'John');
url.searchParams.set('age', '30');

Best Practice 3: Clone URLs When Needed

function modifyUrlWithoutMutating(originalUrl, modifications) {
  const url = new URL(originalUrl.href); // Create new instance

  Object.entries(modifications).forEach(([key, value]) => {
    url.searchParams.set(key, value);
  });

  return url;
}

Browser Support and Polyfills

The URL() and URLSearchParams APIs have excellent browser support:

URL: Supported in all modern browsers (Chrome 32+, Firefox 26+, Safari 7+, Edge 12+)
URLSearchParams: Supported in all modern browsers (Chrome 49+, Firefox 44+, Safari 10.3+, Edge 17+)

For older browsers, you can use the url-polyfill package:

import 'url-polyfill';

// Now URL and URLSearchParams work in older browsers

Conclusion

The URL() and URLSearchParams APIs represent a massive improvement over manual URL string manipulation. They provide:

Type safety: Automatic encoding and validation
Simplicity: Intuitive methods for common operations
Reliability: Handle edge cases correctly
Maintainability: Self-documenting code
Standards compliance: Following web standards

Whether you're building SPAs, working with APIs, managing client-side routing, or handling form submissions, these APIs should be your go-to tools for URL manipulation.

Take Your JavaScript Skills Further

If you found this deep dive valuable, you'll love what we're building at TekBreed – a comprehensive learning platform designed specifically for software engineers who want to master modern web development.

At TekBreed, we create in-depth, practical courses that go beyond surface-level tutorials. We focus on the "why" behind the code, real-world applications, and the tiny details that separate good developers from great ones.

🚀 The waitlist is now live at tekbreed.com

We're currently in active development and planning to launch in Q1 2026. Join the waitlist to:

Get early access to our platform
Receive exclusive content and tutorials
Help shape the courses we create
Be part of a community of passionate engineers

We're building something special for developers who refuse to settle for shallow understanding. See you at TekBreed! 🎯

DEV Community: Christopher S. Aondona

Building Memory-Native AI Agents in TypeScript with MemoFS

Installation

1. Initializing the MemoFS Engine

Storage Modes Supported by @memofs/core

2. Generating Task-Aware Context Briefings

3. Writing Durable Memories with Secret Filtering

Built-in Safety & Sanitization

4. Handling Stale Memory with Graph Relationships

5. End-to-End Example: Complete Agent Loop

Summary of Core API Reference

Resources & Documentation

Supercharging AI Coding Agents & Custom Agent Runtimes with Persistent Memory: A Detailed Cookbook

Cookbook Overview: How MemoFS Connects to Agents

Step 1: Initialize MemoFS in Your Repository

Step 2: Configure Your Specific Agent or Runtime

Option A: Claude Code & OpenAI Codex (Automatic Zero-Touch Hooks)

Option B: Cursor IDE (via MCP)

Option C: GitHub Copilot / VS Code

Option C: Any other coding agent that speak MCP

Option E: Custom Agent Runtimes & Frameworks (via @memofs/core SDK)

Step 3: Record Memories & Test Context Persistence

Recording Memories via CLI

Automatic Memory Extraction During Agent Sessions

Step 4: Verify Memory Health with memofs doctor

Summary of Agent Support Matrix

Next Steps & Further Reading

Why AI Agents Lose Their Memory And How MemoFS Solves It

Context Windows Are Working Memory, Not Long-Term Memory

Why Vector Databases Fall Short for Local & Workspace Agent Workflows

The MemoFS Solution: File-First Memory Runtimes

The 6 Memory Layers of .memofs/

6 Engineering Disciplines Behind MemoFS

1. Canonical Storage vs. Disposable Indexes

2. Write-Time Intelligence & Secret Rejection

3. Solving Memory Staleness with supersedes Graph Edges

4. Zero-Key Hybrid Recall

5. Multi-Interface Access: Hooks, MCP & Core SDK

6. Forensic Auditability & Security

Getting Started: For Agent Users & Agent Builders

For Agent Users (CLI & IDE Setup in 2 Minutes)

For Agent Builders (Programmatic @memofs/core SDK)

Explore Further

Building MemoFS

I am using MemoFS in MemoFS to build MemoFS

Reciprocal Rerank Fusion (RRF): The Simple, Powerful Way to Combine Keyword + Semantic Search in RAG

How RRF Works

TypeScript Implementation

Working with LangChain.js

Why RRF is So Effective

Best Practices in TypeScript Projects

Token Jaccard Similarity in TypeScript: Simple Text Comparison

What is Jaccard Similarity?

Token Jaccard = Jaccard applied to words

Quick Example

TypeScript Implementation

Another Example

Real-World Use Cases

Limitations & Quick Improvements

Easy Upgrades

When to Use It

Conclusion

The Markdown File That Beat a $50M Vector Database: Separating Storage and Search in Agent Memory

The Core Invariant: Storage vs. Search

Write-Path Intelligence: Structuring Memories

Making the Search Index Disposable

The Real-World Tradeoffs

1. Concurrency

2. Memory Poisoning (MINJA)

Introducing TekMemo

Build a Full-Stack Todo App with React & Node.js - The Complete Walkthrough

What We're Building

Step 1: Project Setup

🤔 Before we continue...

Step 2: Backend Setup

🤔 Stop and think...

Step 3: Frontend Setup

🤔 Understanding check...

Step 4: Run It

Challenges For You

Storage Modes Supported by `@memofs/core`

Option E: Custom Agent Runtimes & Frameworks (via `@memofs/core` SDK)

Step 4: Verify Memory Health with `memofs doctor`

The 6 Memory Layers of `.memofs/`

3. Solving Memory Staleness with `supersedes` Graph Edges

For Agent Builders (Programmatic `@memofs/core` SDK)