Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { readFile, readdir } from "node:fs/promises";
import { join, relative } from "node:path";
import test from "node:test";
// Imported, not re-declared: the copies kept here had drifted from sync.mjs
// (dsh, opencode and agent-plugins were all missing modules the sync actually
// ships), so a stale vendored file went unnoticed by this very test.
import { GENERATED_HEADER, ROOT, SHARED_DIR, SKILLS_DIR, SKILL_TARGETS, assembledClosure, resolveTargets } from "./sync.mjs";
test("vendored shared modules are synchronized", async () => {
const files = (await readdir(SHARED_DIR)).filter((file) => file.endsWith(".mjs")).sort();
assert.ok(files.length > 0, "expected shared modules");
for (const target of await resolveTargets()) {
for (const file of target.files) {
assert.ok(files.includes(file), `${file} is in ${relative(ROOT, target.dir)}'s closure but missing from lib/`);
const expected = `${GENERATED_HEADER}${await readFile(join(SHARED_DIR, file), "utf-8")}`;
const actual = await readFile(join(target.dir, file), "utf-8");
assert.equal(
actual,
expected,
`${relative(ROOT, join(target.dir, file))} is out of sync; run node examples/memory-plugin-shared/sync.mjs`,
);
}
}
});
// The two directions the hand-kept lists used to get wrong: a module a plugin
// imports but does not ship is ERR_MODULE_NOT_FOUND on the first hook of a
// fresh install, and one it ships but never imports is dead weight that still
// lands in every review diff. Both sides are derived from the imports now, so
// this asserts what is on disk agrees with them.
test("what each plugin ships equals the closure of what it imports", async () => {
for (const target of await resolveTargets()) {
const onDisk = [];
for (const name of (await readdir(target.dir)).filter((file) => file.endsWith(".mjs")).sort()) {
// A target dir may also hold plugin-local modules; only a file carrying
// the banner is a generated copy this sync owns.
const body = await readFile(join(target.dir, name), "utf-8");
if (body.startsWith(GENERATED_HEADER)) onDisk.push(name);
}
assert.deepEqual(
onDisk,
target.files,
`${relative(ROOT, target.dir)} does not hold the closure of its imports; run node examples/memory-plugin-shared/sync.mjs`,
);
}
});
// Which copies git holds is a delivery decision, and getting it backwards fails
// in a way nobody sees until an install breaks: a committed plugin whose copies
// were ignored ships nothing, and a packaged plugin whose copies were committed
// taxes every review diff with 12,000 generated lines.
test("git holds the copies the directory-installed plugins need, and no others", async () => {
const targets = [
...(await resolveTargets()),
// A skill copy is delivered by path, never regenerated by the host, so
// every one of them is committed; the flag is here to be asserted on.
...SKILL_TARGETS.map((target) => ({ ...target, dir: join(target.dir, target.skill) })),
];
for (const target of targets) {
const dir = relative(ROOT, target.dir);
const tracked = execFileSync("git", ["ls-files", "--", dir], { cwd: ROOT, encoding: "utf-8" })
.split("\n")
.filter(Boolean);
if (target.committed) {
assert.ok(tracked.length > 0, `${dir} is installed from this repository, so its copies must be committed`);
} else {
assert.deepEqual(tracked, [], `${dir} is generated at pack time; it must not be committed`);
}
}
});
// The portable bundle is the one target whose copies are both committed and
// carried by hosts that install it as a plain directory, so every module it
// reaches is committed code a reviewer reads. It has no hooks and no knobs; the
// connection half of the shared loader (`buildProxyConnection`) is what keeps
// it at five modules instead of the whole schema-and-workspace closure.
test("the portable agent-plugins bundle stays connection-only", async () => {
const target = (await resolveTargets())
.find((entry) => relative(ROOT, entry.dir) === join("agent-plugins", "servers", "shared"));
assert.ok(target, "the agent-plugins bundle must stay a sync target");
assert.deepEqual(target.files, [
"credentials.mjs",
"debug-log.mjs",
"mcp-proxy-config.mjs",
"mcp-proxy-core.mjs",
"ov-http.mjs",
]);
});
// A module lib/ carries that no plugin reaches is a capability with no consumer:
// either a harness lost its wiring, or the module should go.
test("every shared module is reachable from some plugin", async () => {
const targets = await resolveTargets();
const claimed = new Set(targets.flatMap((target) => target.files));
// cursor, trae and zcode vendor nothing: the installer assembles their
// runtime instead, so they claim through the manifest it reads.
for (const entry of await assembledClosure()) claimed.add(entry);
const files = (await readdir(SHARED_DIR)).filter((file) => file.endsWith(".mjs")).sort();
assert.deepEqual(
files.filter((file) => !claimed.has(file)),
[],
"shared modules that no plugin imports",
);
});
test("vendored skills are byte-identical to examples/skills", async () => {
for (const { skill, dir } of SKILL_TARGETS) {
const files = (await readdir(join(SKILLS_DIR, skill))).sort();
assert.ok(files.includes("SKILL.md"), `${skill} must ship a SKILL.md`);
const target = join(dir, skill);
assert.deepEqual(
(await readdir(target)).sort(),
files,
`${relative(ROOT, target)} has a different file set; run node examples/memory-plugin-shared/sync.mjs`,
);
for (const file of files) {
assert.equal(
await readFile(join(target, file), "utf-8"),
await readFile(join(SKILLS_DIR, skill, file), "utf-8"),
`${relative(ROOT, join(target, file))} is out of sync; run node examples/memory-plugin-shared/sync.mjs`,
);
}
}
});
// copySkill copies a flat file list; a subdirectory would crash the sync.
test("synced skills keep a flat file layout", async () => {
for (const skill of new Set(SKILL_TARGETS.map((target) => target.skill))) {
const entries = await readdir(join(SKILLS_DIR, skill), { withFileTypes: true });
assert.deepEqual(
entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name),
[],
`examples/skills/${skill} must not contain subdirectories`,
);
}
});
// Skill loaders reject a description longer than this, and the skill then
// silently fails to load. Guard every SKILL.md we ship, synced or not.
const MAX_DESCRIPTION_LENGTH = 1024;
function readDescription(source) {
const frontmatter = /^---\n([\s\S]*?)\n---\n/.exec(source);
if (!frontmatter) return null;
const lines = frontmatter[1].split("\n");
const start = lines.findIndex((line) => /^description:/.test(line));
if (start === -1) return null;
const head = lines[start].slice("description:".length).trim();
if (head && head !== ">" && head !== "|" && head !== ">-" && head !== "|-") {
return head.replace(/^["']|["']$/g, "");
}
const body = [];
for (const line of lines.slice(start + 1)) {
if (/^\S/.test(line)) break;
body.push(line.trim());
}
return body.join(" ").trim();
}
async function findSkillFiles(dir) {
const found = [];
for (const entry of await readdir(dir, { withFileTypes: true })) {
if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
const full = join(dir, entry.name);
if (entry.isDirectory()) found.push(...(await findSkillFiles(full)));
else if (entry.name === "SKILL.md") found.push(full);
}
return found;
}
// viking://~ is the home alias for the caller's own space, and a server older
// than the alias rejects it outright instead of searching. A skill that sends
// the agent to the Experience root therefore has to name the explicit
// viking://user/<user_id> root it falls back to, or the whole workflow stops
// against those servers.
test("skills scoping the Experience root document the explicit-root fallback", async () => {
const files = [
...(await findSkillFiles(join(ROOT, "examples"))),
...(await findSkillFiles(join(ROOT, "agent-plugins"))),
];
const scoped = [];
for (const file of files) {
const source = await readFile(file, "utf-8");
if (!source.includes("viking://~/memories/experiences")) continue;
scoped.push(file);
assert.match(
source,
/viking:\/\/user\/<user_id>/,
`${relative(ROOT, file)} scopes by viking://~ without naming the viking://user/<user_id> fallback`,
);
}
assert.ok(scoped.length > 0, "expected at least one skill scoping the Experience root");
});
test("shipped skill descriptions stay within the loader limit", async () => {
const files = await findSkillFiles(join(ROOT, "examples"));
assert.ok(files.length > 0, "expected at least one SKILL.md");
for (const file of files) {
const description = readDescription(await readFile(file, "utf-8"));
assert.ok(description, `${relative(ROOT, file)} has no frontmatter description`);
assert.ok(
description.length <= MAX_DESCRIPTION_LENGTH,
`${relative(ROOT, file)} description is ${description.length} chars, over the ${MAX_DESCRIPTION_LENGTH} limit`,
);
}
});