🧠 Neural Memory

Neural Memory is a local-first personal cognitive memory assistant and second brain. It turns the desktop context you choose to share into an autonomous, searchable knowledge graph — anchoring real-world micro-feedback (like an "Ok" to an email quote), tracking commitments and decisions, and exposing your context directly to AI tools via the Model Context Protocol (MCP).

⚡ Quick Start: Choose Your Track

Neural Memory offers a Dual-Track Architecture designed for both casual MacBook users and developer power users:

Track B: Standalone Packed Installer (Recommended for Users)

Zero prerequisites. No Docker, no Python, no Homebrew, no terminal commands.

1. Download NeuralMemoryAgent-0.2.0-Installer.dmg (approx. 112 MB).
2. Open the disk image and drag NeuralMemoryAgent.app to your Applications folder.
3. Launch the app from Applications.
   • The interactive Visual Setup Wizard guides you through macOS Accessibility and Screen Recording setup.
   • Starts an embedded native daemon in under 0.2 seconds.
   • Stores all data locally in ~/Library/Application Support/NeuralMemory/memory.db.
   • Access the menu bar icon, temporal graph, and settings instantly.
   • Full guide: docs/STANDALONE_INSTALLER.md.

Track A: Open Local Development Stack (For Developers)

Full Docker Compose + Neo4j 5.26 Community Graph Database.

git clone https://github.com/Hexecu/mcp-neuralmemory.git
cd mcp-neuralmemory
./scripts/bootstrap.sh

• Verifies installation: ./scripts/doctor.sh
• Graph API: http://127.0.0.1:8765/health
• Neo4j Browser: http://127.0.0.1:8774 (User: neo4j, Password in .env)
• Stop without losing data: make down
• Re-start: make up

🌟 Why Neural Memory is Different

• 🔒 PrivacyShield Redaction: In-memory regex and Luhn checksum filtering automatically masks credit cards, IBANs, API keys (sk-..., AIza..., GitHub tokens), and ignores password vaults (1Password, Bitwarden, Keychain).
• 🎯 Contextual Micro-Feedback Anchoring: Eliminates arbitrary length cutoffs. When you type "Ok, proceed with the 5,000 EUR quote", vision analysis anchors your consent directly to the sender, amount, and proposal document.
• 🌌 Temporal Knowledge Graph:
  • Regional Topic Clusters: Orbital regional gravity organizes entities into clean thematic galaxies without central collapse.
  • Timeline Stream: Horizontal chronological layout with 5 semantic altitude lanes (Reflections, Decisions, Meetings, Commitments, Topics).
  • Time-Travel Scrubber: Interactive slider to replay memory history with Ebbinghaus memory decay ($R = e^{-\Delta t / S}$).

📚 Complete Documentation Website

🌐 Interactive Documentation Site: hexecu.github.io/mcp-neuralmemory

🤖 Connect to AI Agents (Claude Desktop & Cursor)

Neural Memory exposes your second brain directly to AI assistants:

# Auto-configure Claude Desktop:
./scripts/setup-mcp.sh --claude

Available MCP Tools for Agents:

• recall_decisions(topic, person): Recalls past strategic agreements and approvals.
• recall_commitments(status, debtor, creditor): Recalls deliverables, action items, and deadlines.
• recall_meetings(topic, attendee): Recalls discussion points and participants from calls.
• get_daily_briefing(date): Generates an executive summary of the day.
• search(query): Deep hybrid search across your accumulated memory graph.

Example conversation:

User: "Claude, what did I agree to send to Marco this Friday?"
Claude: "According to your Neural Memory, you committed to send the updated Cloud proposal slides to Marco Rossi by Friday at 18:00."

🛠️ Developer & Makefile Commands

make help          # Show all available commands
make package       # Build the standalone macOS DMG installer (Zero Docker required)
make verify-clean  # Verify the standalone app in a clean, isolated MacBook simulation
make test-massive  # Run the full 5-stage massive stress, scale, chaos & UI test suite
make test          # Run Python unit & chaos tests (74 tests)
make e2e           # Run end-to-end API integration tests (9 tests)
make doctor        # Verify Docker, API, and Neo4j health
make lint          # Run ruff linter

📄 License

MIT License. See LICENSE for details.