#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
feat: filesystem connector — emits observations on file changes (#62)
Rohit Ghumarebfcff26cc1ed
diff --git a/integrations/filesystem-watcher/README.md b/integrations/filesystem-watcher/README.mdnew file mode 100644index 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.mjsnew file mode 100755index 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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([]);+ });+});