ninaivagam (நினைவகம்)

ninaivagam (Tamil: நினைவகம், "memory/remembrance") is an open-source MCP (Model Context Protocol) server that gives AI coding agents (like Claude Code, Cursor, and Cline) a persistent, project-scoped memory backed by MongoDB.

Whenever you work across different chat sessions, branches, or days, your AI agent won't lose context. It intelligently stores and retrieves structured knowledge about your software projects: folder layouts, architecture decisions, tech stacks, git branch strategies, coding conventions, and in-progress tasks.

🚀 Quick Setup (Step by Step)

1. Start MongoDB

Ninaivagam relies on MongoDB to store project memories. The quickest way to get it running is via Docker:

docker run -d -p 27017:27017 --name mongo mongo:7

(If you already have a MongoDB cluster, you can just use its connection URI!)

2. Initialize in Your Project

Navigate to the root directory of your project (where you want your AI to remember things) and run the initialization command:

npx -y ninaivagam init

This magic command does the heavy lifting:

• Automatically derives a unique projectId based on your package.json and Git remote.
• Outputs the exact JSON settings you need to drop into Claude Code or Cursor.
• Generates a customized rule block that explicitly teaches your AI agent how and when to fetch or save project memories using the MCP.

3. Connect Your AI Agent

For Claude Code

The init command will output a snippet. Add it to either:

• Your global config: ~/.claude/settings.json
• A project-specific config: .claude/settings.json

Example:

{
  "mcpServers": {
    "ninaivagam": {
      "command": "npx",
      "args": ["-y", "ninaivagam"],
      "env": {
        "MONGO_URI": "mongodb://localhost:27017"
      }
    }
  }
}

For Cursor

Open Cursor Settings > MCP > Add server:

• Type: command
• Command: npx
• Args: ["-y", "ninaivagam"]
• Env: MONGO_URI=mongodb://localhost:27017

Make sure to refresh and confirm the server shows as connected!

4. Provide Instructions to the AI

The init command will print out a block of instructions bordered by ---. Copy that block and paste it into your IDE's instruction file so the AI knows to start using its new memory!

• For Cursor: Create .cursor/rules/ninaivagam.mdc
• For Claude Code: Add to CLAUDE.md
• For Windsurf: Add to .windsurfrules

🛠️ Available MCP Tools

Once connected, your AI agent will automatically have access to these core tools:

| Tool | Inputs | Purpose | |------|--------|---------| | store_memory | projectId, category, key, value, tags? | Create or overwrite a memory entry | | retrieve_memory | projectId, key, category? | Fetch a specific memory by key | | list_memories | projectId, category?, tags?, limit? | List memories (with optional category/tag filtering) | | delete_memory | projectId, category, key | Remove a memory entry |

Memory Categories

You can organize memories using the following predefined categories: architecture · stack · folder-structure · git · convention · task · decision · other · branch · environment · release · feature-flag · reference · business-logic · troubleshooting

🔒 Security (Deep Secret Scanning)

Ninaivagam includes a built-in secret scanner that proactively blocks the persistence of sensitive credentials (like AWS keys, OpenAI keys, or connection strings).

• Deep Scanning: The scanner doesn't just check the value field; it recursively scans JSON objects in meta and all entries in tags.
• Global Coverage: Scanning is enforced during manual store_memory calls as well as during bulk operations like ninaivagam import and ninaivagam sync.
• Non-Destructive: During bulk imports, Ninaivagam will skip individual entries that contain secrets while allowing the rest of the file to import successfully.

⚖️ Handling Ambiguity

Since multiple memory categories can share the same key (e.g., a "database" entry in stack and another in convention), Ninaivagam enforces specificity:

• If you call retrieve_memory WITHOUT a category and multiple matches exist, Ninaivagam will return an ambiguity warning listing all available categories for that key.
• This prevents your AI agent from receiving incorrect context and forces it to be explicit in its retrieval strategy.

📃 License

MIT License