memwiki 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+<h1 align="center">🧠 memwiki</h1>
+<p align="center">
+  <strong>A zero-friction, persistent project memory protocol for AI agents.</strong>
+</p>
+<p align="center">
+  <img alt="NPM Version" src="https://img.shields.io/npm/v/memwiki?color=blue&style=flat-square">
+  <img alt="License" src="https://img.shields.io/npm/l/memwiki?style=flat-square">
+  <img alt="Zero Dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square">
+</p>
+
+---
+
+AI coding agents (like Cursor, Claude Code, GitHub Copilot) suffer from "Agent Amnesia". When you start a new session, the agent forgets why certain architectural decisions were made, the project's tech stack quirks, known bugs, and the immediate context.
+
+`memwiki` gives your project a persistent brain. It leverages the fact that modern AI agents naturally read markdown files in your workspace, providing a standardized, vendor-agnostic memory system without requiring complex plugins or subscriptions.
+
+## Getting Started
+
+Initialize `memwiki` in the root of any project:
+
+```bash
+npx memwiki init
+```
+
+That's it. Your project now has a persistent memory.
+
+### Updating the Protocol
+As `memwiki` evolves and we release better agent prompts and slash commands, you can update your existing project's protocol files without overwriting your actual memory wiki:
+
+```bash
+npx memwiki update
+```
+This safely updates `AGENTS.md` and your root hooks (`.cursorrules`, `CLAUDE.md`, etc.) while leaving the contents of `.memory/wiki/` completely untouched.
+
+## How It Works
+
+When you run `npx memwiki init`, it creates a `.memory` directory and places specific hook files (`.cursorrules`, `CLAUDE.md`, `.github/copilot-instructions.md`) directly in your project root. 
+
+These root files act as the automatic "front door" for any AI agent that connects to your repository, explicitly instructing them: *"Hey! I have a brain. Please read `AGENTS.md` and `.memory/wiki/hot.md` before doing anything else."*
+
+### The Folder Structure
+
+```text
+[Project Root]
+├── .cursorrules           (Hook for Cursor)
+├── .github/copilot-instructions.md (Hook for Copilot)
+├── CLAUDE.md              (Hook for Claude Code)
+├── AGENTS.md              (The master protocol file)
+└── .memory/
+    ├── .raw/              (Immutable source documents dropped by humans)
+    └── wiki/
+        ├── hot.md         (Hot cache: recent context & next steps - READ FIRST)
+        ├── index.md       (Table of contents)
+        ├── log.md         (Append-only changelog)
+        ├── stack.md       (Tech stack details)
+        ├── patterns.md    (Coding patterns and conventions)
+        ├── bugs.md        (Known issues and quirks)
+        └── decisions.md   (Architecture Decision Records)
+```
+
+### Reading & Synthesizing
+
+1. **The Hot Cache (`hot.md`)**: Agents read this file *first*. It contains immediate, short-term context (~500 words). It tells the agent exactly what was being worked on and the immediate next steps.
+2. **Immutable Sources (`.raw/`)**: Drop your PDF API docs, GitHub gists, or meeting notes here. Agents are instructed to *read* these files but *never* modify them. 
+   - **How it works:** When you drop a file like `stripe-api.pdf` into `.raw/`, you simply tell your agent: *"Please process the new Stripe docs in the raw folder."* The agent will read the PDF and synthesize the important architectural details into a clean markdown file inside the `wiki/` folder, leaving the original PDF untouched as a source of truth.
+
+### Autonomous Updating
+
+Because modern AI tools have file editing capabilities, the `AGENTS.md` protocol contains explicit instructions for the agent to maintain the wiki proactively:
+
+- "Whenever you learn a new coding pattern, fix a complex bug, or make a significant architectural decision, edit the corresponding file in \`.memory/wiki/\`."
+- "Before ending a session, you MUST update \`.memory/wiki/hot.md\` with the current state and next steps, and append a summary to \`log.md\`."
+
+## Using `memwiki` on Existing Projects
+
+If you initialize `memwiki` on a project that has been in development for months, the `.memory/wiki/` files will start out mostly blank. How does the memory fill up?
+
+There are two ways the memory gets populated:
+
+**1. Organic Growth (The Lazy Way)**  
+You don't *have* to do anything. As you continue working on the project and asking your AI agent to fix bugs or build features, the agent will naturally explore your codebase. Because of the rules in `AGENTS.md`, whenever the agent learns an established pattern or makes a new architectural decision during a session, it will automatically document it in the wiki.
+
+**2. Active Ingestion (The Fast Way)**  
+If you want the memory populated immediately, you can use one of the built-in agent slash commands.
+
+### Scaling to Enterprise Projects
+Are you worried that a single `patterns.md` file will grow to thousands of lines in a massive monorepo? Don't be! 
+
+`memwiki` is not limited to the default starter files. The `AGENTS.md` protocol explicitly instructs your AI agent to **create new markdown files and subdirectories** as the project grows. 
+For example, if you build a complex authentication system, the agent will dynamically create `.memory/wiki/auth-system.md` and link it to the master `index.md`. The `index.md` file acts as a Map of Content (MOC), routing the agent to the right domain-specific files without overflowing the context window.
+
+### Agent Slash Commands
+
+Because `AGENTS.md` explicitly teaches your AI tool how to behave, it also gives your agent "commands" you can run in your chat interface:
+
+- `/memwiki-ingest`: The agent will scan your entire repository and populate `stack.md`, `patterns.md`, and `decisions.md` based on what it finds.
+- `/memwiki-lint`: The agent will perform a health check on the wiki, fixing outdated information or filling in missing context.
+- `/memwiki-fold`: The agent will condense older entries in `log.md` into a clean summary to prevent the log from becoming too large.
+
+## Why `memwiki`?
+
+- **Zero Friction:** One command setup.
+- **Zero Lock-in:** It's just Markdown. 
+- **Universal Compatibility:** Works seamlessly with Cursor, Claude, Copilot, or any tool that reads local files.
+- **Team Scalability:** Ensures that whether a team member uses Cursor or Gemini, they both operate on the exact same project context.
+
+## Inspired By
+This pattern is heavily inspired by Andrej Karpathy's [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).

package/dist/index.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const command = process.argv[2];
+if (command !== 'init' && command !== 'update') {
+    console.log('Usage: npx memwiki init | npx memwiki update');
+    process.exit(1);
+}
+console.log(`Running memwiki ${command}...`);
+const targetDir = process.cwd();
+const files = {
+    // --- Root Hook Files ---
+    '.cursorrules': `# MemWiki Integration
+ALWAYS start your session by reading \`AGENTS.md\` and \`.memory/wiki/hot.md\` to get project context before suggesting code or answering questions.
+`,
+    '.github/copilot-instructions.md': `# MemWiki Integration
+ALWAYS read \`AGENTS.md\` and \`.memory/wiki/hot.md\` to understand the project context, tech stack, and immediate next steps before coding.
+`,
+    'CLAUDE.md': `# MemWiki Integration
+Please read \`AGENTS.md\` and \`.memory/wiki/hot.md\` as your primary source of truth for this project before answering any queries or making changes.
+`,
+    // --- The Protocol ---
+    'AGENTS.md': `# MemWiki Protocol: Agent Instructions
+
+This project uses **MemWiki** (inspired by the [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)), a persistent compounding knowledge base for AI coding agents.
+
+## 1. Session Start (Reading)
+Whenever you start a new session or task, you MUST:
+1. READ \`.memory/wiki/hot.md\` immediately. This contains the immediate context, current state, and next steps.
+2. If \`hot.md\` does not have enough context, consult \`.memory/wiki/index.md\` to find relevant domain pages.
+3. If the user drops new API docs, PDF specs, or gists into \`.memory/.raw/\`, read them to understand the new information, but **never modify the files in \`.raw/\`**.
+
+## 2. During Work (Synthesizing)
+Whenever you learn a new coding pattern, fix a complex bug, or make a significant architectural decision:
+- You MUST edit the corresponding file in \`.memory/wiki/\` (e.g., \`patterns.md\`, \`bugs.md\`, \`decisions.md\`).
+- **Scale the Wiki:** If the project is large, DO NOT cram everything into the default files. Create new markdown files or subdirectories in \`.memory/wiki/\` for specific features, domains, or microservices (e.g., \`.memory/wiki/auth-system.md\`).
+- If you create a new file, you MUST add a link to it in \`.memory/wiki/index.md\`.
+- Synthesize any raw knowledge from \`.memory/.raw/\` into the wiki pages.
+- Never delete knowledge from the wiki. Only append or refine.
+
+## 3. Session End (Updating)
+Before ending a session, completing a major task, or when you are about to lose context:
+1. **Update Hot Cache:** You MUST update \`.memory/wiki/hot.md\` with the current state of the project and the immediate next steps for the next agent.
+2. **Log Work:** You MUST append a timestamped summary of your work to \`.memory/wiki/log.md\`.
+
+## 4. Agent Slash Commands
+The user may invoke specific commands. When you see these commands in the chat, execute the corresponding workflow:
+
+- \`/memwiki-ingest\`: Trigger an active ingestion pass. Scan the entire repository and populate \`stack.md\`, \`patterns.md\`, and \`decisions.md\` based on your findings.
+- \`/memwiki-lint\`: Perform a health check on the wiki. Look for outdated information, missing context in \`hot.md\`, or empty domain pages, and propose fixes.
+- \`/memwiki-fold\`: Condense older entries in \`log.md\` into a summarized paragraph to keep the file from becoming too long, while preserving crucial history.
+`,
+    // --- The Wiki Files ---
+    '.memory/wiki/hot.md': `# Hot Cache
+
+*This file is read first by agents to get immediate context. Agents must update this at the end of every session.*
+
+## Current State
+- Project initialized with MemWiki.
+
+## Immediate Next Steps
+- [ ] Define the project scope.
+- [ ] Set up the initial tech stack.
+`,
+    '.memory/wiki/index.md': `# Project Wiki
+
+*The central directory for all project knowledge.*
+
+- [[hot.md]]: Immediate context and next steps.
+- [[log.md]]: Append-only changelog of agent sessions.
+- [[stack.md]]: Tech stack details and versions.
+- [[patterns.md]]: Established coding patterns and conventions.
+- [[bugs.md]]: Known issues, quirks, and workarounds.
+- [[decisions.md]]: Architecture Decision Records (ADRs).
+
+*(Agents: Create new files for specific features or domains as the project scales, and link them here).*
+`,
+    '.memory/wiki/log.md': `# Work Log
+
+*Append-only changelog. Agents must append a timestamped summary of their work here at the end of each session.*
+
+## Initial Setup
+- Project memory initialized via MemWiki.
+`,
+    '.memory/wiki/stack.md': `# Tech Stack
+
+*Document the core technologies, versions, and deployment details here.*
+
+`,
+    '.memory/wiki/patterns.md': `# Coding Patterns
+
+*Document established coding conventions, file structures, and UI/UX patterns here.*
+
+`,
+    '.memory/wiki/bugs.md': `# Known Bugs & Quirks
+
+*Document unresolved issues, edge cases, and weird system quirks here to prevent future agents from falling into the same traps.*
+
+`,
+    '.memory/wiki/decisions.md': `# Architectural Decisions
+
+*Document major technical decisions, the rationale behind them, and alternatives considered.*
+
+`
+};
+const createDirIfNotExists = (dir) => {
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+};
+// Ensure .memory directories exist
+createDirIfNotExists(path_1.default.join(targetDir, '.github'));
+createDirIfNotExists(path_1.default.join(targetDir, '.memory', '.raw'));
+createDirIfNotExists(path_1.default.join(targetDir, '.memory', 'wiki'));
+let updatedCount = 0;
+for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path_1.default.join(targetDir, relativePath);
+    const isProtocolFile = relativePath === 'AGENTS.md' || relativePath === '.cursorrules' || relativePath === '.github/copilot-instructions.md' || relativePath === 'CLAUDE.md';
+    if (command === 'update' && isProtocolFile) {
+        fs_1.default.writeFileSync(filePath, content, 'utf8');
+        console.log(`🔄 Updated: ${relativePath}`);
+        updatedCount++;
+    }
+    else if (!fs_1.default.existsSync(filePath)) {
+        fs_1.default.writeFileSync(filePath, content, 'utf8');
+        console.log(`✅ Created: ${relativePath}`);
+        updatedCount++;
+    }
+    else {
+        console.log(`⚠️ Skipped (already exists): ${relativePath}`);
+    }
+}
+if (updatedCount > 0) {
+    console.log(`\n🚀 MemWiki ${command} completed successfully!`);
+}
+else {
+    console.log('\n✅ Everything is already up to date.');
+}

package/dist/src/index.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const command = process.argv[2];
+if (command !== 'init') {
+    console.log('Usage: npx memwiki init');
+    process.exit(1);
+}
+console.log('Initializing memwiki project memory protocol...');
+const targetDir = process.cwd();
+const files = {
+    // --- Root Hook Files ---
+    '.cursorrules': `# MemWiki Integration
+ALWAYS start your session by reading \`AGENTS.md\` and \`.memory/wiki/hot.md\` to get project context before suggesting code or answering questions.
+`,
+    '.github/copilot-instructions.md': `# MemWiki Integration
+ALWAYS read \`AGENTS.md\` and \`.memory/wiki/hot.md\` to understand the project context, tech stack, and immediate next steps before coding.
+`,
+    'CLAUDE.md': `# MemWiki Integration
+Please read \`AGENTS.md\` and \`.memory/wiki/hot.md\` as your primary source of truth for this project before answering any queries or making changes.
+`,
+    // --- The Protocol ---
+    'AGENTS.md': `# MemWiki Protocol: Agent Instructions
+
+This project uses **MemWiki**, a persistent compounding knowledge base for AI coding agents.
+
+## 1. Session Start (Reading)
+Whenever you start a new session or task, you MUST:
+1. READ \`.memory/wiki/hot.md\` immediately. This contains the immediate context, current state, and next steps.
+2. If \`hot.md\` does not have enough context, consult \`.memory/wiki/index.md\` to find relevant domain pages.
+3. If the user drops new API docs, PDF specs, or gists into \`.memory/.raw/\`, read them to understand the new information, but **never modify the files in \`.raw/\`**.
+
+## 2. During Work (Synthesizing)
+Whenever you learn a new coding pattern, fix a complex bug, or make a significant architectural decision:
+- You MUST edit the corresponding file in \`.memory/wiki/\` (e.g., \`patterns.md\`, \`bugs.md\`, \`decisions.md\`).
+- Synthesize any raw knowledge from \`.memory/.raw/\` into the wiki pages.
+- Never delete knowledge from the wiki. Only append or refine.
+
+## 3. Session End (Updating)
+Before ending a session, completing a major task, or when you are about to lose context:
+1. **Update Hot Cache:** You MUST update \`.memory/wiki/hot.md\` with the current state of the project and the immediate next steps for the next agent.
+2. **Log Work:** You MUST append a timestamped summary of your work to \`.memory/wiki/log.md\`.
+`,
+    // --- The Wiki Files ---
+    '.memory/wiki/hot.md': `# Hot Cache
+
+*This file is read first by agents to get immediate context. Agents must update this at the end of every session.*
+
+## Current State
+- Project initialized with MemWiki.
+
+## Immediate Next Steps
+- [ ] Define the project scope.
+- [ ] Set up the initial tech stack.
+`,
+    '.memory/wiki/index.md': `# Project Wiki
+
+*The central directory for all project knowledge.*
+
+- [[hot.md]]: Immediate context and next steps.
+- [[log.md]]: Append-only changelog of agent sessions.
+- [[stack.md]]: Tech stack details and versions.
+- [[patterns.md]]: Established coding patterns and conventions.
+- [[bugs.md]]: Known issues, quirks, and workarounds.
+- [[decisions.md]]: Architecture Decision Records (ADRs).
+`,
+    '.memory/wiki/log.md': `# Work Log
+
+*Append-only changelog. Agents must append a timestamped summary of their work here at the end of each session.*
+
+## Initial Setup
+- Project memory initialized via MemWiki.
+`,
+    '.memory/wiki/stack.md': `# Tech Stack
+
+*Document the core technologies, versions, and deployment details here.*
+
+`,
+    '.memory/wiki/patterns.md': `# Coding Patterns
+
+*Document established coding conventions, file structures, and UI/UX patterns here.*
+
+`,
+    '.memory/wiki/bugs.md': `# Known Bugs & Quirks
+
+*Document unresolved issues, edge cases, and weird system quirks here to prevent future agents from falling into the same traps.*
+
+`,
+    '.memory/wiki/decisions.md': `# Architectural Decisions
+
+*Document major technical decisions, the rationale behind them, and alternatives considered.*
+
+`
+};
+const createDirIfNotExists = (dir) => {
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+};
+// Ensure .memory directories exist
+createDirIfNotExists(path_1.default.join(targetDir, '.github'));
+createDirIfNotExists(path_1.default.join(targetDir, '.memory', '.raw'));
+createDirIfNotExists(path_1.default.join(targetDir, '.memory', 'wiki'));
+let createdCount = 0;
+for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path_1.default.join(targetDir, relativePath);
+    if (!fs_1.default.existsSync(filePath)) {
+        fs_1.default.writeFileSync(filePath, content, 'utf8');
+        console.log(`✅ Created: ${relativePath}`);
+        createdCount++;
+    }
+    else {
+        console.log(`⚠️ Skipped (already exists): ${relativePath}`);
+    }
+}
+if (createdCount > 0) {
+    console.log('\n🚀 MemWiki initialized successfully! Your AI agent now has a persistent brain.');
+}
+else {
+    console.log('\n✅ MemWiki was already initialized.');
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "memwiki",
+  "version": "1.0.0",
+  "description": "A zero-friction persistent memory protocol for AI agents.",
+  "main": "dist/index.js",
+  "bin": {
+    "memwiki": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "memory",
+    "wiki",
+    "cursor",
+    "claude",
+    "copilot",
+    "llm"
+  ],
+  "author": "Swapnil",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  }
+}