delx-memory AGENTS.md

Agent Development Notes

Scope

This repo is a local-first persistent memory MCP server. It stores small key/value entries in SQLite for AI agents to share across sessions and across tools.

Commands

• Install: npm ci
• Typecheck: npm run typecheck
• Build: npm run build
• Fast smoke: npm run smoke
• Full gate: npm test

Rules

• Never commit a .sqlite file, a .env, or any real user memory contents.
• Keep the secret-detector patterns conservative on the KEY side (false positives are fine — users can pick a different key name) and high-specificity on the VALUE side (false positives there would block legitimate notes containing words like "token", "refresh", "secret").
• Every mutating tool must require explicit_user_intent: true. Do not add a tool that mutates without it.
• Tools that mutate must preserve idempotence where reasonable (e.g. memory_forget returns existed: false rather than throwing on missing key).
• Keep the per-value cap at 64 KB. This is a tripwire against blob-storage misuse.
• Tests must use ephemeral tmpdirs (mkdtempSync) and clean up. Never let a test write to ~/.delx-memory/.
• No telemetry. No outbound network calls anywhere in the package except over the HTTP transport when the user opts in.

Agent-readiness checklist

Before publishing a new version:

1. npm test clean
2. npm pack --dry-run — confirm only dist/, docs, examples/, server.json, llms.txt are packaged
3. git log -p | grep -iE 'token|secret|api_key' — confirm no real credentials slipped in
4. Bump version in package.json, server.json, and src/constants.ts together
5. Update CHANGELOG.md