@vishnuvmx/recall-memory 0.0.0-stage → 0.1.0

package/dist/templates/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Always-on instruction installed into the agent file (AGENTS.md by default).
+ *
+ * TOKEN BUDGET: this text is injected into EVERY agent turn, so it is capped at
+ * ~120 tokens and enforced by tests/budget.test.ts. It must also be STATIC
+ * (never embed dynamic state): changing always-on text invalidates provider
+ * prompt caches and silently multiplies cost. Detail belongs in the on-demand
+ * skill (ANTIGRAVITY_SKILL_BODY), not here.
+ */
+export declare const AGENT_BLOCK = "## Project memory (Recall)\nMemory is in `.recall/`. Don't read it upfront; skip it for routine edits.\n- Unfamiliar area or design question: `recall context \"<topic>\"`\n- Find a symbol or file: `recall where <name>`\n- Learned a non-obvious rule or bug cause: `recall remember \"<text>\" -t \"<title>\" --type <decision|convention|lesson>`\nSessions are logged automatically; no wrap-up needed.";
+/** Kept so `recall init` can recognize and migrate files written by older versions. */
+export declare const LEGACY_SKILL_MARKER = "# Recall Agent Protocol";
+export declare const MEMORY_MD = "# Project Memory\n\nShort overview of this project. Edit this file by hand; Recall never overwrites it.\n\n## Critical constraints\n\n- (Add the few rules that must never be broken.)\n\n## Where to look\n\nDetailed knowledge is indexed in [INDEX.md](INDEX.md). Search it with `recall context \"<task>\"`.\n";
+export declare const RULE_TEMPLATES: Record<string, string>;
+export declare const CHANGELOG_MD = "# Recall changelog\n\nLocal log of memory operations. Git history is authoritative when available.\n\n";
+/**
+ * On-demand skill: only its name + description are always visible to the agent;
+ * the body is loaded when the agent decides it is relevant. Detail lives here.
+ */
+export declare const SKILL_FRONTMATTER = "---\nname: recall\ndescription: Project memory lookups (context, where) and recording learnings.\n---";
+export declare const ANTIGRAVITY_SKILL_BODY = "# Recall\n\nProject memory lives in `.recall/` as Markdown. Use it to avoid re-discovering things, not as a ritual.\n\n## Look things up (pull, never push)\n- `recall context \"<topic>\"`: past decisions, conventions, and lessons. Output is capped (~400 tokens). Verify claims against current code.\n- `recall where <symbol-or-path>`: `file:line` locations from a cached symbol scan. Open only the lines you need.\n- Continuing earlier work: read `.recall/CURRENT_STATE.md`. It is history, not a to-do list.\n\n## Record what future sessions need\n- `recall remember \"<text>\" -t \"<title>\" --type <decision|convention|lesson|bugfix|failed_approach>`\n- Record only non-obvious knowledge: why a design was chosen, invariants, root causes, dead ends.\n- Re-recording a similar title updates the existing memory instead of duplicating it.\n- Never store secrets (writes containing them are rejected).\n\n## Don't\n- Don't read `.recall/` files wholesale or \"orient\" before simple tasks.\n- Don't run a checkpoint at the end of a session; a hook records it automatically.";

package/dist/templates/index.js

@@ -0,0 +1,62 @@
+/**
+ * Always-on instruction installed into the agent file (AGENTS.md by default).
+ *
+ * TOKEN BUDGET: this text is injected into EVERY agent turn, so it is capped at
+ * ~120 tokens and enforced by tests/budget.test.ts. It must also be STATIC
+ * (never embed dynamic state): changing always-on text invalidates provider
+ * prompt caches and silently multiplies cost. Detail belongs in the on-demand
+ * skill (ANTIGRAVITY_SKILL_BODY), not here.
+ */
+export const AGENT_BLOCK = `## Project memory (Recall)
+Memory is in \`.recall/\`. Don't read it upfront; skip it for routine edits.
+- Unfamiliar area or design question: \`recall context "<topic>"\`
+- Find a symbol or file: \`recall where <name>\`
+- Learned a non-obvious rule or bug cause: \`recall remember "<text>" -t "<title>" --type <decision|convention|lesson>\`
+Sessions are logged automatically; no wrap-up needed.`;
+/** Kept so `recall init` can recognize and migrate files written by older versions. */
+export const LEGACY_SKILL_MARKER = '# Recall Agent Protocol';
+export const MEMORY_MD = `# Project Memory
+
+Short overview of this project. Edit this file by hand; Recall never overwrites it.
+
+## Critical constraints
+
+- (Add the few rules that must never be broken.)
+
+## Where to look
+
+Detailed knowledge is indexed in [INDEX.md](INDEX.md). Search it with \`recall context "<task>"\`.
+`;
+export const RULE_TEMPLATES = {
+    'architecture.md': '# Architecture rules\n\nDescribe the architecture constraints agents must preserve.\n',
+    'coding-style.md': '# Coding style\n\nDescribe naming, formatting, and structure conventions.\n',
+    'design-system.md': '# Design system\n\nList design tokens/components and the checks that enforce them.\n',
+    'workflows.md': '# Workflows\n\nDescribe build, test, and release commands agents should use.\n',
+};
+export const CHANGELOG_MD = '# Recall changelog\n\nLocal log of memory operations. Git history is authoritative when available.\n\n';
+/**
+ * On-demand skill: only its name + description are always visible to the agent;
+ * the body is loaded when the agent decides it is relevant. Detail lives here.
+ */
+export const SKILL_FRONTMATTER = `---
+name: recall
+description: Project memory lookups (context, where) and recording learnings.
+---`;
+export const ANTIGRAVITY_SKILL_BODY = `# Recall
+
+Project memory lives in \`.recall/\` as Markdown. Use it to avoid re-discovering things, not as a ritual.
+
+## Look things up (pull, never push)
+- \`recall context "<topic>"\`: past decisions, conventions, and lessons. Output is capped (~400 tokens). Verify claims against current code.
+- \`recall where <symbol-or-path>\`: \`file:line\` locations from a cached symbol scan. Open only the lines you need.
+- Continuing earlier work: read \`.recall/CURRENT_STATE.md\`. It is history, not a to-do list.
+
+## Record what future sessions need
+- \`recall remember "<text>" -t "<title>" --type <decision|convention|lesson|bugfix|failed_approach>\`
+- Record only non-obvious knowledge: why a design was chosen, invariants, root causes, dead ends.
+- Re-recording a similar title updates the existing memory instead of duplicating it.
+- Never store secrets (writes containing them are rejected).
+
+## Don't
+- Don't read \`.recall/\` files wholesale or "orient" before simple tasks.
+- Don't run a checkpoint at the end of a session; a hook records it automatically.`;

package/dist/utils/fs.d.ts

@@ -0,0 +1,15 @@
+export declare class RecallError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/** Write via temp file + rename so readers never see partial content. */
+export declare function atomicWrite(file: string, data: string): void;
+/** Create a file only if it does not exist. Returns false when it already exists. */
+export declare function writeNew(file: string, data: string): boolean;
+/**
+ * Resolve `parts` under `base`, rejecting traversal and symlink escapes.
+ * Works for paths that do not exist yet (checks the deepest existing ancestor).
+ */
+export declare function resolveInside(base: string, ...parts: string[]): string;
+export declare function toPosix(p: string): string;
+export declare function today(): string;

package/dist/utils/fs.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export class RecallError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+        this.name = 'RecallError';
+    }
+}
+/** Write via temp file + rename so readers never see partial content. */
+export function atomicWrite(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(tmp, data, 'utf8');
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+        throw err;
+    }
+}
+/** Create a file only if it does not exist. Returns false when it already exists. */
+export function writeNew(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+        fs.writeFileSync(file, data, { encoding: 'utf8', flag: 'wx' });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
+function isInside(base, target) {
+    const rel = path.relative(base, target);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/**
+ * Resolve `parts` under `base`, rejecting traversal and symlink escapes.
+ * Works for paths that do not exist yet (checks the deepest existing ancestor).
+ */
+export function resolveInside(base, ...parts) {
+    const target = path.resolve(base, ...parts);
+    if (!isInside(path.resolve(base), target)) {
+        throw new RecallError(`Path escapes the allowed directory: ${parts.join('/')}`);
+    }
+    const realBase = fs.realpathSync(base);
+    let probe = target;
+    while (!fs.existsSync(probe)) {
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break;
+        probe = parent;
+    }
+    if (!isInside(realBase, fs.realpathSync(probe))) {
+        throw new RecallError(`Path resolves outside the allowed directory via a symlink: ${parts.join('/')}`);
+    }
+    return target;
+}
+export function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+export function today() {
+    return new Date().toISOString().slice(0, 10);
+}

package/dist/utils/managed.d.ts

@@ -0,0 +1,5 @@
+/** Replace (or append) a marker-delimited block, preserving everything outside it. */
+export declare function applyManagedBlock(existing: string, block: string, name?: string): string;
+export declare function extractManagedBlock(existing: string, name?: string): string | null;
+/** Remove a marker-delimited block (and its markers), preserving everything else. No-op if absent. */
+export declare function removeManagedBlock(existing: string, name?: string): string;

package/dist/utils/managed.js

@@ -0,0 +1,41 @@
+import { RecallError } from './fs.js';
+/** Replace (or append) a marker-delimited block, preserving everything outside it. */
+export function applyManagedBlock(existing, block, name = 'recall') {
+    const begin = `<!-- ${name}:begin -->`;
+    const end = `<!-- ${name}:end -->`;
+    const wrapped = `${begin}\n${block.trim()}\n${end}`;
+    const b = existing.indexOf(begin);
+    const e = existing.indexOf(end);
+    if (b === -1 && e === -1) {
+        if (existing.trim() === '')
+            return `${wrapped}\n`;
+        return `${existing.replace(/\s*$/, '')}\n\n${wrapped}\n`;
+    }
+    if (b === -1 || e === -1 || e < b || existing.indexOf(begin, b + 1) !== -1) {
+        throw new RecallError(`Malformed Recall markers (${name}). Refusing to modify the file.`, `Fix or remove the "${begin}" / "${end}" lines manually, then retry.`);
+    }
+    return existing.slice(0, b) + wrapped + existing.slice(e + end.length);
+}
+export function extractManagedBlock(existing, name = 'recall') {
+    const begin = `<!-- ${name}:begin -->`;
+    const end = `<!-- ${name}:end -->`;
+    const b = existing.indexOf(begin);
+    const e = existing.indexOf(end);
+    if (b === -1 || e === -1 || e < b)
+        return null;
+    return existing.slice(b + begin.length, e).trim();
+}
+/** Remove a marker-delimited block (and its markers), preserving everything else. No-op if absent. */
+export function removeManagedBlock(existing, name = 'recall') {
+    const begin = `<!-- ${name}:begin -->`;
+    const end = `<!-- ${name}:end -->`;
+    const b = existing.indexOf(begin);
+    const e = existing.indexOf(end);
+    if (b === -1 || e === -1 || e < b)
+        return existing;
+    const before = existing.slice(0, b).replace(/\s*$/, '');
+    const after = existing.slice(e + end.length).replace(/^\s*/, '');
+    if (!before)
+        return after;
+    return after ? `${before}\n\n${after}` : `${before}\n`;
+}

package/dist/utils/secrets.d.ts

@@ -0,0 +1,3 @@
+/** Returns the labels of any secret-looking patterns (never the matched text). */
+export declare function findSecrets(text: string): string[];
+export declare function assertNoSecrets(text: string): void;

package/dist/utils/secrets.js

@@ -0,0 +1,23 @@
+import { RecallError } from './fs.js';
+const PATTERNS = [
+    ['private key', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+    ['AWS access key', /\bAKIA[0-9A-Z]{16}\b/],
+    ['API key (sk-...)', /\bsk-[A-Za-z0-9_-]{20,}/],
+    ['GitHub token', /\bgh[pousr]_[A-Za-z0-9]{30,}/],
+    ['Google API key', /\bAIza[0-9A-Za-z\-_]{35,}\b/],
+    ['Slack token', /\bxox[baprs]-[0-9A-Za-z-]{10,48}\b/],
+    ['Stripe API key', /\b[rs]k_(live|test)_[0-9a-zA-Z]{24,}\b/],
+    ['JWT token', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}\b/],
+    ['connection string with credentials', /\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^:\s]+:[^@\s]+@[a-zA-Z0-9.-]+/],
+    ['credential assignment', /\b(api[_-]?key|secret|token|passwd|password)\b\s*[:=]\s*['"]?[A-Za-z0-9/+_-]{16,}/i],
+];
+/** Returns the labels of any secret-looking patterns (never the matched text). */
+export function findSecrets(text) {
+    return PATTERNS.filter(([, re]) => re.test(text)).map(([label]) => label);
+}
+export function assertNoSecrets(text) {
+    const hits = findSecrets(text);
+    if (hits.length > 0) {
+        throw new RecallError(`Refusing to store content that looks like a secret (${hits.join(', ')}).`, 'Remove the credential and describe it instead (e.g. "API key lives in the env var X").');
+    }
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@vishnuvmx/recall-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Zero-maintenance, local-first persistent project memory for AI coding agents.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "recall": "dist/cli/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vishnuvmx/recall-memory.git"
+  },
+  "homepage": "https://github.com/vishnuvmx/recall-memory#readme",
+  "bugs": {
+    "url": "https://github.com/vishnuvmx/recall-memory/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "coding-agents",
+    "mcp",
+    "antigravity",
+    "claude-code",
+    "cursor"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prebench": "npm run build",
+    "bench": "node scripts/benchmark.js",
+    "prepare": "git config core.hooksPath .githooks || true",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "gray-matter": "^4.0.3",
+    "ignore": "^7.0.12",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}