Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Tiny Bun-native HTTP server stub for embedding-provider tests.
*
* Each test can install a handler that decides what to return for any
* incoming request. The default handler returns OpenAI-shaped vectors
* deterministically derived from the input texts (no randomness — so
* `toBeCloseTo` checks stay stable).
*/
export interface FakeRequest {
readonly method: string;
readonly path: string;
readonly headers: Record<string, string>;
readonly body: unknown;
}
export interface FakeResponseSpec {
status?: number;
headers?: Record<string, string>;
body?: unknown;
delayMs?: number;
}
type Handler = (
req: FakeRequest,
callIndex: number,
) => FakeResponseSpec | Promise<FakeResponseSpec>;
export interface FakeHttp {
url: string;
close: () => Promise<void>;
setHandler: (h: Handler) => void;
/** Number of requests received since creation. */
callCount: () => number;
}
/** Path tail the default handler serves embeddings on. */
const EMBEDDINGS_ROUTE = "/embeddings";
/** Path tail the default handler serves rerank on. */
const RERANK_ROUTE = "/rerank";
/** Model name echoed when a request carries none. */
const DEFAULT_FAKE_MODEL = "fake-model";
/**
* Smoothing that keeps the overlap score in [0, 1) and monotone in the
* number of shared tokens: matches / (matches + SMOOTHING).
*/
const RERANK_OVERLAP_SMOOTHING = 1;
/** Lowercased word tokens with punctuation stripped, deduplicated. */
function tokensOf(text: string): Set<string> {
const out = new Set<string>();
for (const word of text.toLowerCase().split(/\s+/)) {
const token = word.replace(/\p{P}+/gu, "");
if (token !== "") out.add(token);
}
return out;
}
/**
* Deterministic query-document score from token overlap, in [0, 1) and
* monotone in the number of tokens the two share. No randomness and no
* clock, so identical requests replay byte-identically.
*/
function overlapScore(query: string, document: string): number {
const queryTokens = tokensOf(query);
let matches = 0;
for (const token of tokensOf(document)) {
if (queryTokens.has(token)) matches += 1;
}
return matches / (matches + RERANK_OVERLAP_SMOOTHING);
}
interface RerankRequestBody {
model?: string;
query?: unknown;
documents?: unknown;
}
function rerankRoute(req: FakeRequest): FakeResponseSpec {
const body = (req.body ?? {}) as RerankRequestBody;
if (typeof body.query !== "string" || !Array.isArray(body.documents)) {
return { status: 400, body: { error: "rerank request: query and documents are required" } };
}
if (!body.documents.every((d) => typeof d === "string")) {
return { status: 400, body: { error: "rerank request: documents must be strings" } };
}
const query = body.query;
const scored = (body.documents as string[]).map((document, index) => ({
index,
relevance_score: overlapScore(query, document),
}));
// Real providers (Cohere, Jina, TEI) answer in score order, not input
// order, so the default route does too: sorted by relevance_score
// descending, stable on index (Array#sort is stable). The rerank
// client realigns the items back through each item's own `index`, and
// going through the default route keeps that realignment exercised by
// every suite that rides the shared fixture, not only by the suites
// that install an explicit out-of-order handler.
const results = scored.sort((a, b) => b.relevance_score - a.relevance_score);
return { status: 200, body: { results, model: body.model ?? DEFAULT_FAKE_MODEL } };
}
function defaultHandler(req: FakeRequest): FakeResponseSpec {
if (req.path.endsWith(EMBEDDINGS_ROUTE) && req.method === "POST") {
const body = (req.body ?? {}) as { input?: string[]; model?: string };
const inputs = Array.isArray(body.input) ? body.input : [];
const data = inputs.map((text, index) => {
// Deterministic 4-dim vector from token count + position.
const tokens = text.split(/\s+/).filter(Boolean).length;
const v = [tokens, index, text.length, 1];
return { object: "embedding", embedding: v, index };
});
return { status: 200, body: { data, model: body.model ?? DEFAULT_FAKE_MODEL } };
}
if (req.method === "POST" && req.path.endsWith(RERANK_ROUTE)) {
return rerankRoute(req);
}
return { status: 404, body: { error: "not_found" } };
}
/**
* Distinguishes one fake server from every other one this process starts.
*
* The port cannot do it. It is ephemeral, the operating system hands the
* same number back once a server closes, and a process-scoped registry
* keyed by endpoint URL then reads two unrelated test files as one
* endpoint - the embedding concurrency ceiling
* (`embeddings/provider-semaphore.ts`) is exactly that, and refuses by
* design when two configurations disagree about the limit for one
* endpoint. So a file embedding at concurrency 2 failed inside another
* file's ceiling of 1, at whatever rate the port came back around: green
* on nineteen runs and red on the twentieth, in a file that had nothing
* to do with the one that set the limit.
*
* A path segment costs nothing and makes each server what it already is -
* a distinct endpoint. Providers append their own suffix to this base
* (`/embeddings`, `/models/embed`), so handlers that match on the tail of
* the path are unaffected.
*/
let instances = 0;
/** Status a throwing handler answers with. */
const HANDLER_ERROR_STATUS = 500;
export async function startFakeHttp(): Promise<FakeHttp> {
let handler: Handler = defaultHandler;
let count = 0;
// Bun 1.4.0's Server.stop(true) waits for in-flight fetch handlers to
// return, and a stalled-lane test holds one until its (never) answer, so
// teardown under the CI toolchain waited out the stall and the hook
// timeout fired first. The closer therefore settles every in-flight
// handler with a synthetic response before stopping, which costs nothing
// on the newer Bun and keeps "never answers" a legitimate handler shape.
const pending = new Set<(response: FakeResponseSpec) => void>();
const server = Bun.serve({
port: 0,
fetch: async (req) => {
const url = new URL(req.url);
let body: unknown = null;
const ctype = req.headers.get("content-type") ?? "";
if (ctype.startsWith("application/json")) {
try {
body = await req.json();
} catch {
body = null;
}
}
const headers: Record<string, string> = {};
req.headers.forEach((v, k) => {
headers[k] = v;
});
const idx = count++;
const resp = await new Promise<FakeResponseSpec>((resolve) => {
const settle = (value: FakeResponseSpec) => {
pending.delete(settle);
resolve(value);
};
pending.add(settle);
// A handler that throws (or rejects) answers 500 with its message,
// so the test fails on the real error instead of timing out.
Promise.resolve()
.then(() => handler({ method: req.method, path: url.pathname, headers, body }, idx))
.then(settle, (err: unknown) =>
settle({
status: HANDLER_ERROR_STATUS,
body: { error: err instanceof Error ? err.message : String(err) },
}),
);
});
if (resp.delayMs && resp.delayMs > 0) {
await new Promise<void>((r) => setTimeout(r, resp.delayMs));
}
return new Response(resp.body === undefined ? "" : JSON.stringify(resp.body), {
status: resp.status ?? 200,
headers: { "content-type": "application/json", ...resp.headers },
});
},
});
const url = `http://127.0.0.1:${server.port}/i${++instances}/v1`;
return {
url,
close: () => {
for (const settle of pending) settle({ status: 503, body: { error: "server-closing" } });
server.stop(true);
return Promise.resolve();
},
setHandler: (h: Handler) => {
handler = h;
},
callCount: () => count,
};
}