Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

feat: filesystem connector — emits observations on file changes (#62)

Rohit Ghumarebfcff26cc1ed
diff --git a/integrations/filesystem-watcher/README.md b/integrations/filesystem-watcher/README.md
new file mode 100644
index 00000000..36b7e960
--- /dev/null
+++ b/integrations/filesystem-watcher/README.md
@@ -0,0 +1,59 @@
+# @agentmemory/fs-watcher
+
+Filesystem connector for agentmemory. Watches one or more directories and emits an observation to the running agentmemory server every time a file changes.
+
+Part of the data-source-connectors effort tracked in issue #62.
+
+## Install
+
+```bash
+npm install -g @agentmemory/fs-watcher
+```
+
+Or run without installing:
+
+```bash
+npx @agentmemory/fs-watcher ~/work/my-repo
+```
+
+## Usage
+
+```bash
+# CLI args win over env.
+agentmemory-fs-watcher ~/work/my-repo ~/notes
+
+# Or set env once in your shell.
+export AGENTMEMORY_FS_WATCH_DIRS=~/work/my-repo,~/notes
+export AGENTMEMORY_URL=http://localhost:3111
+export AGENTMEMORY_SECRET=... # only if the server requires auth
+agentmemory-fs-watcher
+```
+
+Every file change inside the watched roots becomes a `file_change` observation; deletions become `file_delete`. The first 4 KB of each text file is included as content preview so retrieval can match by substring; larger files are truncated with `truncated: true` in metadata. Binary files are not read (set `AGENTMEMORY_FS_WATCH_ALLOW_BINARY=1` to override).
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `AGENTMEMORY_FS_WATCH_DIRS` | — | Comma-separated list of directories to watch |
+| `AGENTMEMORY_FS_WATCH_IGNORE` | — | Comma-separated regex patterns to ignore (applied to relative paths) |
+| `AGENTMEMORY_FS_WATCH_ALLOW_BINARY` | `0` | `1` to include binary files in the preview read |
+| `AGENTMEMORY_URL` | `http://localhost:3111` | agentmemory server URL |
+| `AGENTMEMORY_SECRET` | — | Bearer token, required if the server has `AGENTMEMORY_SECRET` set |
+| `AGENTMEMORY_PROJECT` | — | Optional project label attached to each observation |
+| `AGENTMEMORY_SESSION_ID` | — | Optional session id to attribute observations to |
+
+## Defaults
+
+Ignored out of the box: `.git/`, `node_modules/`, `dist/`, `build/`, `.next/`, `.turbo/`, `coverage/`, `.DS_Store`, `*.log`, `*.lock`. Extend with `AGENTMEMORY_FS_WATCH_IGNORE`.
+
+Text extensions read for preview: common source, config, and docs (`.ts/.js/.py/.go/.rs/.md/.yaml/...`). Unknown extensions are recorded as a path-only observation without content.
+
+Writes are debounced 500 ms per path so a stream of saves from your editor becomes a single observation.
+
+## Notes
+
+- Uses Node's built-in `fs.watch` with `{ recursive: true }`. Works natively on macOS, Linux, and Windows 10+. No native deps.
+- If `fs.watch` errors on a specific root (permission, platform quirk), the watcher logs and continues on the others.
+- The process must keep running. Use a process manager (`launchd`, `systemd`, `pm2`) to supervise it.
+- This connector is intentionally one-way: it writes observations and never reads the agentmemory store.
diff --git a/integrations/filesystem-watcher/bin.mjs b/integrations/filesystem-watcher/bin.mjs
new file mode 100755
index 00000000..34ebed72
--- /dev/null
+++ b/integrations/filesystem-watcher/bin.mjs
@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { FilesystemWatcher, configFromEnv } from "./watcher.mjs";
+
+const cliArgs = process.argv.slice(2);
+const envCfg = configFromEnv(process.env);
+
+const roots = cliArgs.length > 0 ? cliArgs : envCfg.roots;
+if (!roots || roots.length === 0) {
+ process.stderr.write(
+ "agentmemory-fs-watcher: no directories to watch.\n" +
+ "Usage: agentmemory-fs-watcher <dir> [<dir>...]\n" +
+ "Or set AGENTMEMORY_FS_WATCH_DIRS=path1,path2\n",
+ );
+ process.exit(2);
+}
+
+const watcher = new FilesystemWatcher({ ...envCfg, roots });
+watcher.start();
+process.stderr.write(
+ `[fs-watcher] emitting to ${envCfg.baseUrl || "http://localhost:3111"}\n`,
+);
+
+const shutdown = () => {
+ watcher.stop();
+ process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
diff --git a/integrations/filesystem-watcher/package.json b/integrations/filesystem-watcher/package.json
new file mode 100644
index 00000000..4e049857
--- /dev/null
+++ b/integrations/filesystem-watcher/package.json
@@ -0,0 +1,22 @@
+{
+ "name": "@agentmemory/fs-watcher",
+ "version": "0.1.0",
+ "description": "Filesystem connector for agentmemory — emits observations on file changes.",
+ "type": "module",
+ "bin": {
+ "agentmemory-fs-watcher": "./bin.mjs"
+ },
+ "main": "./watcher.mjs",
+ "exports": {
+ ".": "./watcher.mjs"
+ },
+ "files": ["watcher.mjs", "bin.mjs", "README.md"],
+ "engines": { "node": ">=18" },
+ "license": "Apache-2.0",
+ "homepage": "https://github.com/rohitg00/agentmemory/tree/main/integrations/filesystem-watcher",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/rohitg00/agentmemory.git",
+ "directory": "integrations/filesystem-watcher"
+ }
+}
diff --git a/integrations/filesystem-watcher/watcher.mjs b/integrations/filesystem-watcher/watcher.mjs
new file mode 100644
index 00000000..40fc969f
--- /dev/null
+++ b/integrations/filesystem-watcher/watcher.mjs
@@ -0,0 +1,210 @@
+import { watch, promises as fsp, statSync } from "node:fs";
+import { resolve, relative, join, extname, sep } from "node:path";
+
+const TEXT_EXTENSIONS = new Set([
+ ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+ ".py", ".rb", ".go", ".rs", ".java", ".kt", ".swift",
+ ".c", ".cc", ".cpp", ".h", ".hpp",
+ ".md", ".mdx", ".txt", ".rst",
+ ".json", ".yaml", ".yml", ".toml", ".ini", ".env",
+ ".html", ".css", ".scss", ".vue", ".svelte",
+ ".sh", ".bash", ".zsh", ".fish",
+ ".sql", ".graphql", ".proto",
+]);
+
+const DEFAULT_IGNORE = [
+ /(?:^|\/)\.git(?:\/|$)/,
+ /(?:^|\/)node_modules(?:\/|$)/,
+ /(?:^|\/)dist(?:\/|$)/,
+ /(?:^|\/)build(?:\/|$)/,
+ /(?:^|\/)\.next(?:\/|$)/,
+ /(?:^|\/)\.turbo(?:\/|$)/,
+ /(?:^|\/)coverage(?:\/|$)/,
+ /(?:^|\/)\.DS_Store$/,
+ /\.log$/,
+ /\.lock$/,
+];
+
+const MAX_PREVIEW_BYTES = 4096;
+const DEBOUNCE_MS = 500;
+
+export class FilesystemWatcher {
+ constructor(config = {}) {
+ this.roots = (config.roots || []).map((r) => resolve(r));
+ this.baseUrl = (config.baseUrl || "http://localhost:3111").replace(/\/+$/, "");
+ this.secret = config.secret;
+ this.project = config.project || null;
+ this.sessionId = config.sessionId || null;
+ this.ignore = [...DEFAULT_IGNORE, ...(config.ignorePatterns || [])];
+ this.allowBinary = Boolean(config.allowBinary);
+ this.logger = config.logger || console;
+ this.watchers = [];
+ this.pendingByPath = new Map();
+ }
+
+ isIgnored(path) {
+ return this.ignore.some((re) => re.test(path));
+ }
+
+ isTextFile(path) {
+ if (this.allowBinary) return true;
+ const ext = extname(path).toLowerCase();
+ return TEXT_EXTENSIONS.has(ext);
+ }
+
+ async readPreview(path) {
+ try {
+ const fh = await fsp.open(path, "r");
+ try {
+ const buf = Buffer.alloc(MAX_PREVIEW_BYTES);
+ const { bytesRead } = await fh.read(buf, 0, MAX_PREVIEW_BYTES, 0);
+ return buf.slice(0, bytesRead).toString("utf-8");
+ } finally {
+ await fh.close();
+ }
+ } catch {
+ return null;
+ }
+ }
+
+ async emit(event) {
+ const headers = { "content-type": "application/json" };
+ if (this.secret) headers.authorization = `Bearer ${this.secret}`;
+ try {
+ const res = await fetch(`${this.baseUrl}/agentmemory/observe`, {
+ method: "POST",
+ headers,
+ body: JSON.stringify(event),
+ signal: AbortSignal.timeout(5000),
+ });
+ if (!res.ok) {
+ this.logger.warn?.(
+ `[fs-watcher] observe ${res.status}: ${await res.text().catch(() => "")}`,
+ );
+ }
+ } catch (err) {
+ this.logger.warn?.(`[fs-watcher] observe failed: ${err?.message || err}`);
+ }
+ }
+
+ schedule(rootDir, relPath) {
+ const key = join(rootDir, relPath);
+ const existing = this.pendingByPath.get(key);
+ if (existing) clearTimeout(existing.timer);
+ const timer = setTimeout(() => {
+ this.pendingByPath.delete(key);
+ this.flush(rootDir, relPath).catch((err) =>
+ this.logger.warn?.(`[fs-watcher] flush failed: ${err?.message || err}`),
+ );
+ }, DEBOUNCE_MS);
+ this.pendingByPath.set(key, { timer });
+ }
+
+ async flush(rootDir, relPath) {
+ const absPath = join(rootDir, relPath);
+ if (this.isIgnored(relPath)) return;
+ let exists = true;
+ let size = 0;
+ try {
+ const st = statSync(absPath);
+ if (!st.isFile()) return;
+ size = st.size;
+ } catch {
+ exists = false;
+ }
+ const hookType = exists ? "file_change" : "file_delete";
+ let preview = null;
+ if (exists && this.isTextFile(absPath)) {
+ preview = await this.readPreview(absPath);
+ }
+ const truncated = exists && size > MAX_PREVIEW_BYTES;
+ const payload = {
+ hookType,
+ project: this.project,
+ sessionId: this.sessionId,
+ files: [relPath],
+ content: this.formatContent(relPath, hookType, preview, { size, truncated }),
+ metadata: {
+ source: "filesystem-watcher",
+ rootDir,
+ absPath,
+ size,
+ truncated,
+ },
+ };
+ await this.emit(payload);
+ }
+
+ formatContent(relPath, hookType, preview, { size, truncated }) {
+ if (hookType === "file_delete") return `deleted: ${relPath}`;
+ const head = `${relPath} (${size} bytes${truncated ? ", truncated" : ""})`;
+ if (preview === null) return head;
+ return `${head}\n\n${preview}`;
+ }
+
+ start() {
+ if (this.roots.length === 0) {
+ throw new Error("filesystem-watcher: at least one root directory is required");
+ }
+ for (const root of this.roots) {
+ try {
+ const handle = watch(
+ root,
+ { recursive: true, persistent: true },
+ (_eventType, filename) => {
+ if (!filename) return;
+ const rel = filename.split(sep).join("/");
+ if (this.isIgnored(rel)) return;
+ this.schedule(root, rel);
+ },
+ );
+ handle.on("error", (err) => {
+ this.logger.warn?.(`[fs-watcher] watch error on ${root}: ${err?.message || err}`);
+ });
+ this.watchers.push(handle);
+ this.logger.info?.(`[fs-watcher] watching ${root}`);
+ } catch (err) {
+ this.logger.error?.(
+ `[fs-watcher] failed to watch ${root}: ${err?.message || err}`,
+ );
+ }
+ }
+ }
+
+ stop() {
+ for (const w of this.watchers) {
+ try {
+ w.close();
+ } catch {}
+ }
+ this.watchers = [];
+ for (const { timer } of this.pendingByPath.values()) {
+ clearTimeout(timer);
+ }
+ this.pendingByPath.clear();
+ }
+}
+
+// Small helper used by tests and bin.mjs to parse env.
+export function configFromEnv(env = process.env) {
+ const roots = (env.AGENTMEMORY_FS_WATCH_DIRS || "")
+ .split(",")
+ .map((s) => s.trim())
+ .filter(Boolean);
+ const extraIgnore = (env.AGENTMEMORY_FS_WATCH_IGNORE || "")
+ .split(",")
+ .map((s) => s.trim())
+ .filter(Boolean)
+ .map((s) => new RegExp(s));
+ return {
+ roots,
+ baseUrl: env.AGENTMEMORY_URL,
+ secret: env.AGENTMEMORY_SECRET,
+ project: env.AGENTMEMORY_PROJECT || null,
+ sessionId: env.AGENTMEMORY_SESSION_ID || null,
+ ignorePatterns: extraIgnore,
+ allowBinary: env.AGENTMEMORY_FS_WATCH_ALLOW_BINARY === "1",
+ };
+}
+
+export { relative as _relativeForTests };
diff --git a/test/fs-watcher.test.ts b/test/fs-watcher.test.ts
new file mode 100644
index 00000000..c50e6eda
--- /dev/null
+++ b/test/fs-watcher.test.ts
@@ -0,0 +1,170 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FilesystemWatcher, configFromEnv } from "../integrations/filesystem-watcher/watcher.mjs";
+
+function tempDir(): string {
+ return mkdtempSync(join(tmpdir(), "fs-watch-"));
+}
+
+function wait(ms: number): Promise<void> {
+ return new Promise((r) => setTimeout(r, ms));
+}
+
+describe("FilesystemWatcher", () => {
+ let root: string;
+ const originalFetch = globalThis.fetch;
+ let captured: Array<{ url: string; body: unknown; headers: Record<string, string> }>;
+
+ beforeEach(() => {
+ root = tempDir();
+ captured = [];
+ (globalThis as { fetch: typeof fetch }).fetch = (async (
+ url: string | URL,
+ init?: RequestInit,
+ ) => {
+ captured.push({
+ url: url.toString(),
+ body: init?.body ? JSON.parse(init.body as string) : null,
+ headers: (init?.headers || {}) as Record<string, string>,
+ });
+ return new Response("{}", { status: 200 });
+ }) as unknown as typeof fetch;
+ });
+
+ afterEach(() => {
+ globalThis.fetch = originalFetch;
+ try {
+ rmSync(root, { recursive: true, force: true });
+ } catch {}
+ });
+
+ it("emits a file_change observation when a watched file is written", async () => {
+ const w = new FilesystemWatcher({
+ roots: [root],
+ baseUrl: "http://localhost:3111",
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+ });
+ w.start();
+ try {
+ writeFileSync(join(root, "notes.md"), "hello world\n");
+ await wait(800);
+ expect(captured.length).toBeGreaterThanOrEqual(1);
+ const obs = captured[captured.length - 1];
+ expect(obs.url).toBe("http://localhost:3111/agentmemory/observe");
+ const body = obs.body as { hookType: string; files: string[]; content: string };
+ expect(body.hookType).toBe("file_change");
+ expect(body.files).toContain("notes.md");
+ expect(body.content).toContain("hello world");
+ } finally {
+ w.stop();
+ }
+ });
+
+ it("emits a file_delete observation when a watched file is removed", async () => {
+ writeFileSync(join(root, "old.md"), "bye\n");
+ const w = new FilesystemWatcher({
+ roots: [root],
+ baseUrl: "http://localhost:3111",
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+ });
+ w.start();
+ try {
+ unlinkSync(join(root, "old.md"));
+ await wait(800);
+ const deletes = captured.filter(
+ (c) => (c.body as { hookType: string }).hookType === "file_delete",
+ );
+ expect(deletes.length).toBeGreaterThanOrEqual(1);
+ } finally {
+ w.stop();
+ }
+ });
+
+ it("ignores paths that match the default ignore set", async () => {
+ mkdirSync(join(root, "node_modules"), { recursive: true });
+ const w = new FilesystemWatcher({
+ roots: [root],
+ baseUrl: "http://localhost:3111",
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+ });
+ w.start();
+ try {
+ writeFileSync(join(root, "node_modules", "ignored.js"), "x");
+ await wait(800);
+ const matches = captured.filter((c) =>
+ (c.body as { files: string[] }).files?.some((f) => f.includes("ignored.js")),
+ );
+ expect(matches).toHaveLength(0);
+ } finally {
+ w.stop();
+ }
+ });
+
+ it("attaches Bearer auth when a secret is configured", async () => {
+ const w = new FilesystemWatcher({
+ roots: [root],
+ baseUrl: "http://localhost:3111",
+ secret: "shhh",
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+ });
+ w.start();
+ try {
+ writeFileSync(join(root, "secret.md"), "bearer test\n");
+ await wait(800);
+ expect(captured.length).toBeGreaterThanOrEqual(1);
+ const headers = captured[captured.length - 1].headers as Record<string, string>;
+ expect(headers.authorization).toBe("Bearer shhh");
+ } finally {
+ w.stop();
+ }
+ });
+
+ it("debounces rapid writes to a single observation", async () => {
+ const w = new FilesystemWatcher({
+ roots: [root],
+ baseUrl: "http://localhost:3111",
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+ });
+ w.start();
+ try {
+ const target = join(root, "burst.md");
+ writeFileSync(target, "1\n");
+ writeFileSync(target, "2\n");
+ writeFileSync(target, "3\n");
+ writeFileSync(target, "4\n");
+ await wait(900);
+ const hits = captured.filter((c) =>
+ (c.body as { files: string[] }).files?.[0] === "burst.md",
+ );
+ expect(hits.length).toBeLessThanOrEqual(2);
+ } finally {
+ w.stop();
+ }
+ });
+});
+
+describe("configFromEnv", () => {
+ it("parses comma-separated dirs and ignore patterns", () => {
+ const cfg = configFromEnv({
+ AGENTMEMORY_FS_WATCH_DIRS: " /a , /b ",
+ AGENTMEMORY_FS_WATCH_IGNORE: "foo$, ^bar",
+ AGENTMEMORY_URL: "http://localhost:3111",
+ AGENTMEMORY_SECRET: "tok",
+ AGENTMEMORY_PROJECT: "demo",
+ });
+ expect(cfg.roots).toEqual(["/a", "/b"]);
+ expect(cfg.baseUrl).toBe("http://localhost:3111");
+ expect(cfg.secret).toBe("tok");
+ expect(cfg.project).toBe("demo");
+ expect(cfg.ignorePatterns).toHaveLength(2);
+ expect(cfg.ignorePatterns[0].test("abcfoo")).toBe(true);
+ expect(cfg.ignorePatterns[1].test("barbaz")).toBe(true);
+ });
+
+ it("returns empty roots when the env var is missing", () => {
+ const cfg = configFromEnv({});
+ expect(cfg.roots).toEqual([]);
+ });
+});