🧠 MemoryLink

Git-native memory + safety layer for AI coding assistants

Multi-agent coordination • Safe rollbacks • Context sharing • Safety checks

Why MemoryLink Exists

Modern teams use AI tools and agents everywhere: Cursor, Claude, Copilot, CI bots, and in-house automation. These tools are fast, but they also create new risks that traditional CI and reviews often catch too late.

MemoryLink exists to keep AI and agents from silently damaging your codebase or leaking secrets while you move fast, no matter which tools you use.

What Problems MemoryLink Solves

• AI tools can break critical code: Cursor, Claude, Copilot, and other AI assistants can break auth, change critical logic, or introduce insecure patterns that only show up in production or late security scans.
• Multiple agents conflict: IDE AI, Claude, Copilot, CI bots, and custom agents can touch the same files and silently overwrite each other or create race conditions in one repo.
• Secrets leak into code: AI or rushed developers can accidentally paste cloud keys, API tokens, or passwords into source files that later get pushed to GitHub.

The core problem: Traditional CI, tests, and code review are too late in the flow to catch many AI mistakes while developers move fast.

How MemoryLink Helps

MemoryLink adds a thin safety and coordination layer around any AI, IDE, or agent:

• Protect sensitive areas
  Mark files and directories like .env, src/auth/, or database migrations as protected so changes there get special attention from Buddy-Check.

• Coordinate all agents
  Use locks so only one "agent" (Cursor, Claude, IDE AI, CI job, custom bot) can hold a file or scope at a time, preventing silent overwrites and race conditions.

• Create safe checkpoints
  Take checkpoints before large AI changes, then view diffs and run doctor after, so you see exactly what changed and can roll back quickly.

Simple rule for any workflow:

Whatever AI or agent you use, wrap its work with:
lock → checkpoint → doctor → diff → release.

What is MemoryLink?

MemoryLink is a local-first, Git-native CLI tool that provides shared memory and safety checks for AI coding assistants. It helps teams coordinate multiple AI agents, maintain project context, and catch dangerous changes before they cause problems.

Key principles:

• Local-first: All data stored in .memorylink/ directory
• Git-native: Works with your existing Git workflow
• CLI-focused: Simple commands for daily use
• Safety framework: Buddy-Check system for preflight/postflight validation

What it's NOT:

• Not a universal firewall or 100% detection system
• Not a replacement for code review or security scanning tools
• Not a cloud service (everything is local)

Who is it for?

MemoryLink is designed for:

• JS/TS developers using Cursor AI, VS Code, or GitHub Actions
• Teams working with Git repositories and AI coding assistants
• Developers who need multi-agent coordination and safety checks

Requirements:

• Node.js 18+ (for native fetch support)
• Git repository
• CLI access

What it does today (v1.0.1)

✅ Fully Functional Features

• Multi-agent locking: 100% functional - Prevents concurrent agent access to same files
• Checkpoints: Create, list, diff, and restore memory snapshots
• Buddy-Check framework: Preflight/postflight safety checks with GREEN/YELLOW/RED status
• Memory system: Store and retrieve project context with scopes and weighted filtering
• Stats & observability: Track Buddy-Check runs, metrics, and recommendations
• Basic secret detection: Scans for API keys, tokens, passwords in memory logs
• Protected file tracking: List-based checking for critical files

⚠️ Framework Ready (v1.6)

These features have the framework in place but need enhancements for full detection:

• Full secret/PII detection: Basic patterns exist, enhanced patterns needed
• Protected file detection: List configured, Git diff analysis needed
• File deletion detection: Framework ready, Git diff needed
• Stale memory detection: Context retrieval works, code analysis needed

What it does NOT promise

Important limitations:

• ⚠️ Not 100% detection: No tool achieves 100% detection. MemoryLink uses RED status and exit codes to block clearly dangerous changes where rules apply.
• ⚠️ Not a universal firewall: Focused on AI agent safety, not all security threats. Use alongside dedicated security tools.
• ⚠️ Framework vs. full detection: Some detection is "framework ready" and will be strengthened in v1.6 (Git-diff integration, enhanced patterns).
• ⚠️ Local-only locking: Locks are file-based, not distributed. Multiple machines can't coordinate locks (use Git-based coordination for distributed teams).

What you should do:

• Use MemoryLink in combination with code review, CI/CD, and security scanning tools
• Configure protected files appropriately
• Run Buddy-Check in CI/CD pipelines
• Monitor stats regularly

Quickstart

First 5 Minutes with MemoryLink

Get MemoryLink working in your project in 5 minutes:

1. Install and check:

npm install -g memorylink
memorylink --version
# Should show: 1.0.1

This installs MemoryLink globally and verifies it works.

2. Initialize in your project:

cd your-project
memorylink init

This creates .memorylink/ directory with configuration files.

3. Protect critical files:

memorylink protect .env
memorylink protect src/auth/
memorylink protect prisma/migrations/

This tells MemoryLink which files are sensitive and should be monitored.

4. Run your first health check:

memorylink doctor --preflight
memorylink stats

This runs initial safety checks and shows that MemoryLink is tracking runs.

Now you're ready! MemoryLink is installed, initialized, and tracking your project.

Daily Workflow (With Any AI or Agent)

Use the same pattern whether changes come from Cursor, Claude, Copilot, CI, or your own bots.

Before AI / agent changes:

memorylink lock acquire --agent "cursor" --files "src/"
memorylink checkpoint create --name "before-feature-x"
memorylink doctor --preflight

Let your AI / agent do its work here (Cursor, Claude, Copilot, CI, custom bot, etc.)

After changes:

memorylink doctor --postflight
memorylink checkpoint diff --name "before-feature-x"
memorylink lock release

How this helps:

• Lock: Prevents other agents or tools from editing the same scope at the same time
• Checkpoint: Creates a safe restore point before large AI changes
• Doctor: Scans for risky patterns and changes in protected areas
• Diff: Shows exactly what your AI or agent changed so you can accept, fix, or roll back

CI/CD Integration

Add to your GitHub Actions workflow:

- name: Run Buddy-Check
  run: |
    memorylink doctor --preflight --json > preflight.json
    # Fail on RED status
    if grep -q '"status": "RED"' preflight.json; then
      exit 1
    fi

See GETTING_STARTED.md for detailed setup instructions.

Example Scenarios

These are common situations where MemoryLink protects you.

Scenario 1: AI Refactor Breaks Auth

Problem (without MemoryLink):
An AI assistant (Cursor, Claude, Copilot, etc.) "cleans up" src/auth/ and accidentally removes a critical permission check. The issue is only noticed after users hit production.

With MemoryLink:

# Mark auth as sensitive once
memorylink protect src/auth/

# Before asking any AI to refactor auth
memorylink lock acquire --agent "cursor" --files "src/auth/"
memorylink checkpoint create --name "before-auth-refactor"
memorylink doctor --preflight

# Let your AI refactor auth...

# After AI changes
memorylink doctor --postflight
memorylink checkpoint diff --name "before-auth-refactor"
memorylink lock release

What this does:
MemoryLink treats src/auth/ as high-risk, lets you see exactly what changed, and gives you a clear, local chance to catch problems before they ever reach production.

Without MemoryLink: You discover this in production. With MemoryLink: You get an early, local warning.

Scenario 2: Cloud API Key Leak (The $55k Bill Story)

Problem (without MemoryLink):
A developer (student or professional) accidentally commits a cloud API key to GitHub in config.ts. Automated scanners find it within minutes, abuse the key with thousands of requests, and the developer wakes up to a shocking bill—sometimes tens of thousands of dollars.

Real example: A CS student accidentally committed a Gemini API key, bots found it, made over 14,000 unauthorized requests, and generated a $55,000 cloud bill before the provider waived it after public pressure.

With MemoryLink:

# Protect config files
memorylink protect .env
memorylink protect config/

# After coding or AI changes
memorylink doctor --postflight

What this does:

• Doctor flags secret-like patterns in tracked files (keys, tokens, credentials) before git add / git push
• Gives you a local warning like: "Possible secret found in src/config.ts – are you sure this should be committed?"
• If a key moves from .env into a tracked source file, postflight checks treat that as high-risk and surface it clearly

Without MemoryLink: Key gets committed, bots find it, massive bill arrives. With MemoryLink: You get an early, local warning before the key ever leaves your machine.

Note: MemoryLink is not a billing firewall, but it helps you catch obvious leaked keys locally before bots on GitHub do.

Scenario 3: Secret Accidentally Added to Code

Problem (without MemoryLink):
A cloud key or token gets pasted into config.ts or another source file and is later pushed to GitHub or shared in a bundle.

With MemoryLink:

# After some AI / manual edits
memorylink doctor --postflight

What this does:
If a secret-like pattern appears in tracked files, MemoryLink warns during the postflight doctor step so you delete the secret and rotate it before it leaves your machine.

Without MemoryLink: Secret gets committed and exposed. With MemoryLink: You get a warning before commit.

Scenario 4: Two Agents Fighting Over One File

Problem (without MemoryLink):
An IDE AI and a CI bot both modify src/api.ts. One set of changes silently overwrites the other, and nobody notices until much later.

With MemoryLink:

# Agent 1 (e.g., IDE AI)
memorylink lock acquire --agent "ide-ai" --files "src/api.ts"
# ... edits happen ...
memorylink lock release

# Agent 2 (e.g., CI or another bot)
memorylink lock acquire --agent "ci-bot" --files "src/api.ts"
# If Agent 1 still holds the lock, this call fails with a clear lock error.

What this does:
Locks ensure only one agent owns a file at a time. Instead of silent overwrites, the second agent receives a clear "locked" signal and you decide the correct order of operations.

Without MemoryLink: Silent overwrite, discovered later. With MemoryLink: Second agent is blocked with a clear message.

Core Features

Multi-Agent Locking

Prevent conflicts when multiple AI agents work on the same codebase:

memorylink lock acquire --agent "cursor" --files "src/api.ts"
# Other agents will be blocked until lock is released
memorylink lock release

Status: ✅ 100% functional in v1.0.1

Checkpoints

Create memory snapshots for safe rollback:

memorylink checkpoint create --name "before-refactor"
# ... make changes ...
memorylink checkpoint diff "before-refactor" "current"
memorylink checkpoint restore "before-refactor"

Status: ✅ Functional in v1.0.1

Buddy-Check Safety Framework

Preflight/postflight safety checks:

memorylink doctor --preflight   # Before AI operations
memorylink doctor --postflight  # After AI operations

Returns GREEN (safe), YELLOW (warnings), or RED (block) status.

Status: ✅ Framework ready in v1.0.1 (full detection in v1.6)

Memory & Context

Store and retrieve project context using internal heuristics to rank and filter relevant memories:

memorylink memory "Uses React 18 with TypeScript" --tags frontend
memorylink get-context --smart --task "work on authentication"

Status: ✅ Functional in v1.0.1

Note: The internal ranking and filtering algorithms are proprietary and may evolve.

Stats & Observability

Track Buddy-Check metrics:

memorylink stats
memorylink stats --since 7d --format json

Status: ✅ Functional in v1.0.1

How to Check MemoryLink is Working

Check 1: Lock Behavior

Test that locks actually prevent conflicts:

# Terminal 1
memorylink lock acquire --agent "test-agent" --files "src/test.ts"

# Terminal 2 (try to acquire same lock)
memorylink lock acquire --agent "other-agent" --files "src/test.ts"
# => Should see an error that lock is already held

What you should see: The second lock attempt should be blocked with a clear error message.

Check 2: Secret Detection

Test that Buddy-Check detects potential secrets:

# Add a fake secret to a test file
echo "// FAKE_KEY=AKIA1234567890TEST" >> src/fake-secret-test.ts
memorylink doctor --postflight

What you should see: Doctor should give at least a YELLOW warning about a possible secret detected.

If both checks work: MemoryLink is functioning correctly! Locks block conflicts, and Buddy-Check detects risky patterns.

Documentation

• USER_GUIDE.md: How to use MemoryLink in daily workflow and handle common problems
• GETTING_STARTED.md: Step-by-step setup for JS/TS + Cursor + GitHub Actions
• FEATURES.md: Detailed explanation of all features
• SECURITY_MODEL.md: What safety features do/don't do, limits, how to use safely
• ROADMAP_v1.6.md: What's coming next (Git diff, enhanced patterns, contradiction checks)
• RELEASE_NOTES_v1.0.1.md: What's in this version

Installation

Requirements

• Node.js: 18.0.0 or higher (for native fetch support)
• Git: Required for hooks and team sharing
• npm: For installation

Install

npm install -g memorylink

Verify Installation

memorylink --version
# Should output: 1.0.1

Initialize in Project

cd your-project
memorylink init

This creates .memorylink/ directory with configuration files.

Support & Community

• GitHub: mspworld/memorylink
• Issues: Report bugs or request features
• Documentation: See docs in this repository

How MemoryLink Works in a Team

MemoryLink is designed for team collaboration with shared memory across multiple developers and AI tools.

Per-Repo, Shared Memory

MemoryLink stores its logs in .memorylink/ inside your Git repository. This means:

• When teammates pull the repo, they can access the same shared memory (if .memorylink/ files are committed)
• Any AI/agent integrated with that repo (Cursor, Claude, VS Code, CI bots) can read from the same .memorylink/ state
• One project brain per repo - all tools and developers share the same context

How to Share Memory

MemoryLink supports two patterns for memory sharing:

1. Shared Team Memory (Committed Logs)

Best for: Long-term learnings, decisions, conventions, and project knowledge

# Team commits selected .memorylink/ files
git add .memorylink/memory.log .memorylink/rules.md
git commit -m "Add team learnings and conventions"

What this enables:

• Everyone sees the same history, conventions, and learnings
• New team members get context immediately
• AI tools (Cursor, Claude, etc.) have access to team knowledge
• Decisions and patterns are preserved across the team

2. Local Private Memory

Best for: Sensitive logs, noisy runtime data, personal notes

# .gitignore already excludes these by default
.memorylink/*.log
.memorylink/telemetry.log
.memorylink/observability.log

What this enables:

• Developers keep their own local logs that are not pushed
• Sensitive or noisy runtime logs stay private
• Personal notes and experiments remain local

Multi-Agent & Multi-Tool Behavior

Multiple tools can all use the same MemoryLink protocol:

• Same .memorylink/ structure - all tools read/write to the same files
• Same workflow pattern - lock → checkpoint → doctor → diff → release
• No manual sync needed - tools automatically share memory through Git

Supported tools:

• Cursor AI
• VS Code (with extensions)
• Claude (via CLI)
• GitHub Actions / CI bots
• Custom automation scripts

Example: Team Knowledge Sharing

Scenario:

1. Dev A uses Cursor with MemoryLink and logs a learning: "Auth bug fixed: always check X before Y."
2. Dev A commits .memorylink/memory.log to the repo.
3. Dev B later uses Gemini Studio on the same repo.
4. MemoryLink gives that learning to Gemini too (through the same .memorylink/ files).
5. Result: Tools share knowledge; team doesn't repeat the same mistakes.

Benefits:

• ✅ Knowledge persists across team members
• ✅ AI tools learn from each other's work
• ✅ No need to manually document patterns
• ✅ Context is automatically available to all tools

License

MemoryLink uses the MemoryLink Community License (source-available, restricted commercial use).

What this means:

• ✅ Source-available: You can read and modify the code
• ✅ Free for personal and internal use: Use MemoryLink freely for personal projects and internal company use
• ❌ Commercial restrictions: Running a competing hosted SaaS or selling MemoryLink as a product requires a commercial agreement
• ❌ No white-labeling: Removing branding and reselling as your own product is not permitted

Full license terms: See LICENSE file for complete details.

Commercial licensing: For commercial use that falls under restrictions, contact MemoryLink to discuss a commercial license agreement.

MemoryLink v1.0.1 - Ready for production use with JS/TS + Cursor/VS Code + GitHub Actions