NeuroSync 🧠

Give your AI a permanent memory of your project. NeuroSync silently learns your codebase and feeds that knowledge to GitHub Copilot and every AI agent you use — automatically, every session.

Why Use NeuroSync?

AI coding assistants forget everything between sessions. Every new chat they have no idea:

• What naming conventions or code style your project uses
• Architecture decisions you made last week
• Known bug traps and gotchas in your codebase
• What stack you are running (Spring Boot, Flutter, Next.js, etc.)

You end up re-explaining your project over and over — wasting tokens and getting generic answers.

NeuroSync fixes this. It runs silently in the background, builds a ranked memory of your project, and writes it into the context files that Copilot and every major AI agent reads automatically before responding.

Features

🔄 Auto Memory — Always On

NeuroSync watches all source files across your project as you work — zero configuration:

• All languages: TypeScript, JavaScript, Java, Kotlin, Dart, Python, Go, Rust, C#, Ruby, Swift, CSS/SCSS, Markdown, YAML, TOML, XML, Gradle, Properties
• Auto-classified: every file change is tagged with domain (java, flutter, typescript, python, config…), category (gotcha, convention, decision, fix…), and smart content tags
• Smart deduplication: saves the same file 20 times in 5 minutes → merges into one observation with boosted confidence — no noise

🗂️ Stack Auto-Detection

NeuroSync reads your project files once on startup and auto-detects what you're building — no setup:

📄 Context File Sync — 30s Debounced

Every 30 seconds after a file change, NeuroSync rebuilds your AI context files. Only writes when content actually changed — never triggers false watcher loops.

Files written automatically:

🎯 Smart Ranked Context

The context written to these files is not generic — it is ranked by relevance:

• Gotchas first — highest-risk observations surface first (Spring @Transactional traps, Flutter BuildContext async gaps, Python mutable defaults…)
• Score threshold — only observations with meaningful signal are included; one-off file saves are excluded automatically
• Hard token cap — max 8 gotchas + 8 conventions + 6 decisions + 5 fixes + 5 learned patterns ≈ 1,100 tokens. Never bloats.
• Stack label — detected stack is always at the top so the AI knows your tech without being told

Auto-Gitignore

On first activation, NeuroSync automatically adds all its private/generated files to your .gitignore:

.neurosync/.context-key
.neurosync/store.json
.neurosync/rules/
.neurosync/agent-rules.md
.agent-mem/
.agent/skills/auto/

🤖 GitHub Copilot Agent Mode — LM Tools

NeuroSync registers three tools that Copilot's agent mode calls on-demand — no setup, no MCP config:

These tools mean the agent only pays token cost when it actually needs deep context — not on every query.

🎓 Domain Skill Rulebooks — Per Language

NeuroSync compiles per-domain expert guides into .agent/skills/auto/ every 20 observations:

• Java / Spring Boot — @Transactional proxy rules, JPA N+1, DTO discipline, Bean scope, security
• Flutter / Dart — mounted checks after await, const widget optimization, BLoC/Riverpod patterns, isolate safety
• Python — mutable defaults, type hints, secrets vs random, async event loop rules
• TypeScript — strict typing, async patterns, export conventions
• React — hooks rules, key props, rendering gotchas
• Config — env file safety, lock file practices

Agents load only the rulebook relevant to the file they're editing.

✂️ Automatic Store Pruning

NeuroSync keeps the memory store lean automatically. When observations exceed 500:

• All manually-saved notes are always kept
• Observations confirmed multiple times are always kept
• Recent observations (last 7 days) are always kept
• Older, low-signal entries are pruned by quality score

Advanced Usage (Optional)

Everything above works without any manual input. The features below are for users who want more control.

1. Save a Note (20 seconds)

Capture something important immediately — a gotcha you just hit, a decision just made, a fix that took hours:

Command Palette → NeuroSync: Save Note

You'll be guided through 5 quick steps:

1. Pick a category (Gotcha / Convention / Decision / Fix / Practice…)
2. Write a short title (e.g. Never use date-fns, we use dayjs)
3. Add detail (optional — what happened, why it matters)
4. Tag it (optional — auth, api, db…)
5. Confirm

The note is encrypted, stored, and appears in the next context sync.

2. Write Architecture Rules

Edit .neurosync/ip_rules.md — these rules are injected at the top of every AI context file with a CRITICAL label. The AI reads them before writing any code.

Use this to enforce hard project rules that must never be violated:

NEVER use TailwindCSS in this project. Only CSS Modules.
All API routes must be versioned: /api/v1/
Use Zustand for global state. No Redux.
Database access only through the Repository layer. No direct Prisma calls in controllers.

NeuroSync never overwrites this file — it is always your content.

3. Save Lessons (You or the AI)

Edit .agent/lessons.md — a running log of hard-learned lessons that every context sync injects under CORE LESSONS (SELF-CORRECTION).

You can write entries yourself, or tell Copilot to write one:

"Add to .agent/lessons.md: Never call setState after an await without checking mounted first — causes Flutter crash in production."

On the next sync, that lesson appears in every context file. The AI will never repeat that mistake.

4. Search Memory

Command Palette → NeuroSync: Search Memory

Full TF-IDF search across everything NeuroSync has observed. Finds results even when you use different wording (stemming handles authenticate ≈ auth ≈ authorized).

5. Configure Sync Targets

By default NeuroSync writes to 4 context files. You can control this in Settings → neurosync.syncTargets:

"neurosync.syncTargets": [
  "CLAUDE.md",
  "AGENTS.md",
  ".github/copilot-instructions.md",
  "docs/ai-context.md"
]

Add any path — NeuroSync writes plain Markdown there.

6. Configure Auto-Watch

"neurosync.autoWatch": true   // default — disable if you only want manual notes

Getting Started

1. Install the extension from the VS Code Marketplace
2. Open any workspace — NeuroSync activates automatically
3. The 🧠 panel appears in the Activity Bar — shows live stats
4. Edit files as usual — observations are logged silently
5. After 30 seconds of inactivity, context files are written automatically
6. Your AI agent now has full project context — every session, no setup

That's it. No API keys, no accounts, no config files required.

Commands

Open the Command Palette (Ctrl+Shift+P) and type NeuroSync:

All commands are also available as buttons in the sidebar panel.

Note Categories

Settings

Privacy & Security

• All data stays on your machine — no cloud sync, no remote storage, no accounts
• AES-256-GCM encryption with a per-workspace key stored locally
• Zero telemetry — NeuroSync never phones home
• Open source — inspect every line of what runs on your machine