kyp-mem 0.2.0 → 0.2.2

package/README.md

@@ -1,21 +1,27 @@
 # KYP-MEM — Know Your Project Memory
 
-**Headless Obsidian for AI agents.** A markdown knowledge base with wikilinks, backlinks, tags, related notes, and a neon web UI — all powered by an MCP server so Claude (or any AI) can read and write your project knowledge directly.
+**Headless knowledge base for AI agents.** Markdown notes with wikilinks, backlinks, tags, related notes, and a neon web UI — all powered by an MCP server so Claude (or any AI) can read and write your project knowledge directly.
 
 ## Install
 
 ```bash
-pip install kyp-mem
+npx -y kyp-mem
+```
+
+Or install the command globally:
+
+```bash
+npm install -g kyp-mem
 ```
 
 ## Setup (3 commands)
 
 ```bash
 # 1. Choose where your vault (knowledge base) lives
-kyp-mem init
+npx -y kyp-mem init
 
 # 2. Connect to Claude Code — auto-configures MCP
-kyp-mem setup-claude
+npx -y kyp-mem setup-claude
 
 # 3. Restart Claude Code — done!
 #    kyp-mem now runs headlessly every session.
@@ -27,10 +33,10 @@ That's it. Claude now has `kyp_read`, `kyp_write`, `kyp_search`, and 7 other too
 ## Optional: Web UI
 
 ```bash
-kyp-mem ui
+npx -y kyp-mem ui
 ```
 
-Opens an Obsidian-like interface at `localhost:3333` with:
+Opens a rich interface at `localhost:3333` with:
 - Collapsible folder tree
 - Rendered markdown with syntax highlighting
 - Clickable `[[wikilinks]]`
@@ -50,7 +56,7 @@ Opens an Obsidian-like interface at `localhost:3333` with:
 ```
 
 - **Headless by default** — runs as an MCP server (stdio), no GUI needed
-- **Markdown files on disk** — same format as Obsidian, no database
+- **Markdown files on disk** — plain `.md` files with YAML frontmatter, no database
 - **In-memory index** — links, backlinks, tags, search, similarity scoring
 - **Web UI optional** — `kyp-mem ui` when you want to browse visually
 
@@ -59,7 +65,7 @@ Opens an Obsidian-like interface at `localhost:3333` with:
 | Command | What it does |
 |---------|-------------|
 | `kyp-mem init` | First-time setup — choose vault location |
-| `kyp-mem setup-claude` | Auto-configure Claude Code MCP settings |
+| `kyp-mem setup-claude` | Register the MCP server with Claude Code for this project |
 | `kyp-mem setup-claude --global` | Configure globally (all projects) |
 | `kyp-mem serve` | Start MCP server (used by Claude, not you) |
 | `kyp-mem ui` | Open web UI at localhost:3333 |
@@ -83,7 +89,7 @@ Opens an Obsidian-like interface at `localhost:3333` with:
 
 ## Note Format
 
-Standard markdown with YAML frontmatter — same as Obsidian:
+Standard markdown with YAML frontmatter:
 
 ```markdown
 ---
@@ -104,21 +110,11 @@ Settings are defined in `HedgeConfig`. See [[Risk Management]] for safety checks
 
 If you prefer to configure manually instead of using `setup-claude`:
 
-```json
-{
-  "mcpServers": {
-    "kyp-mem": {
-      "command": "kyp-mem",
-      "args": ["serve"],
-      "env": {
-        "KYP_VAULT": "~/.kyp-mem/vault"
-      }
-    }
-  }
-}
+```bash
+claude mcp add -s local -e KYP_VAULT="$HOME/.kyp-mem/vault" kyp-mem -- npx -y kyp-mem serve
 ```
 
-Add to `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project).
+Use `-s user` instead of `-s local` to make it available in all projects.
 
 ## Architecture
 
@@ -134,12 +130,10 @@ Add to `~/.claude/settings.json` (global) or `.claude/settings.json` (per-projec
         └── ...
 ```
 
-## Publishing to PyPI
+## Publishing to npm
 
 ```bash
-pip install build twine
-python3 -m build
-twine upload dist/*
+npm publish
 ```
 
 ## License

package/bin/cli.mjs

@@ -1,33 +1,68 @@
 #!/usr/bin/env node
 
-import { execFileSync, execSync } from "child_process";
+import { spawnSync } from "child_process";
+import { delimiter, dirname, resolve } from "path";
+import { fileURLToPath } from "url";
 
 const args = process.argv.slice(2);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
 
-function tryRun(cmd, cmdArgs) {
-  try {
-    execFileSync(cmd, cmdArgs, { stdio: "inherit" });
-    return true;
-  } catch {
-    return false;
+const env = {
+  ...process.env,
+  PYTHONPATH: process.env.PYTHONPATH
+    ? `${root}${delimiter}${process.env.PYTHONPATH}`
+    : root,
+};
+
+function run(command, cmdArgs, stdio = "ignore") {
+  return spawnSync(command, cmdArgs, { stdio, env });
+}
+
+function pythonCandidates() {
+  if (process.env.KYP_MEM_PYTHON) {
+    return [[process.env.KYP_MEM_PYTHON, []]];
+  }
+
+  const candidates = [
+    ["python3", []],
+    ["python", []],
+  ];
+
+  if (process.platform === "win32") {
+    candidates.unshift(["py", ["-3"]]);
+  }
+
+  return candidates;
+}
+
+function findPython() {
+  for (const [command, prefixArgs] of pythonCandidates()) {
+    const result = run(command, [...prefixArgs, "--version"]);
+    if (result.status === 0) {
+      return [command, prefixArgs];
+    }
   }
+
+  return null;
 }
 
-// Try the installed kyp-mem binary first
-if (tryRun("kyp-mem", args)) process.exit(0);
+const python = findPython();
 
-// Fallback: python3 -m kyp_mem.cli
-if (tryRun("python3", ["-m", "kyp_mem.cli", ...args])) process.exit(0);
+if (python) {
+  const [command, prefixArgs] = python;
+  const result = run(command, [...prefixArgs, "-m", "kyp_mem.cli", ...args], "inherit");
 
-// Fallback: python -m kyp_mem.cli
-if (tryRun("python", ["-m", "kyp_mem.cli", ...args])) process.exit(0);
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+
+  process.exit(result.status ?? 1);
+}
 
 console.error("");
-console.error("  \x1b[31mError:\x1b[0m kyp-mem Python package not found.");
+console.error("  \x1b[31mError:\x1b[0m Python 3 was not found.");
 console.error("");
-console.error("  Install it:");
-console.error("    \x1b[33mpip install kyp-mem\x1b[0m");
-console.error("  Or from source:");
-console.error("    \x1b[33mpip install git+https://github.com/Adhithya-Karthikeyan/KYP-MEM.git\x1b[0m");
+console.error("  Install Python 3.10+ and rerun this command.");
 console.error("");
 process.exit(1);

package/bin/install.mjs

@@ -1,36 +1,77 @@
 #!/usr/bin/env node
 
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "..");
 
-function tryInstall(cmd) {
-  try {
-    execSync(cmd, { cwd: root, stdio: "pipe" });
-    return true;
-  } catch {
-    return false;
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    cwd: root,
+    stdio: options.stdio ?? "ignore",
+    env: {
+      ...process.env,
+      PIP_DISABLE_PIP_VERSION_CHECK: "1",
+    },
+  });
+}
+
+function pythonCandidates() {
+  if (process.env.KYP_MEM_PYTHON) {
+    return [[process.env.KYP_MEM_PYTHON, []]];
+  }
+
+  const candidates = [
+    ["python3", []],
+    ["python", []],
+  ];
+
+  if (process.platform === "win32") {
+    candidates.unshift(["py", ["-3"]]);
   }
+
+  return candidates;
+}
+
+function findPython() {
+  for (const [command, prefixArgs] of pythonCandidates()) {
+    const result = run(command, [...prefixArgs, "--version"]);
+    if (result.status === 0) {
+      return [command, prefixArgs];
+    }
+  }
+
+  return null;
 }
 
-// Check if already installed
-try {
-  execSync("kyp-mem --help", { stdio: "pipe" });
+if (process.env.KYP_MEM_SKIP_PYTHON_INSTALL === "1") {
   process.exit(0);
-} catch {}
+}
+
+const python = findPython();
+
+if (!python) {
+  console.log("  \x1b[33m!\x1b[0m Python 3 was not found.");
+  console.log("  \x1b[33m!\x1b[0m Install Python 3.10+ and run: python3 -m pip install --user .");
+  process.exit(0);
+}
+
+const [pythonCommand, pythonPrefixArgs] = python;
 
 console.log("  Installing kyp-mem Python package...");
 
-if (tryInstall("pip install --user .")) {
-  console.log("  \x1b[32m✓\x1b[0m kyp-mem installed successfully");
-} else if (tryInstall("pip3 install --user .")) {
-  console.log("  \x1b[32m✓\x1b[0m kyp-mem installed successfully");
-} else if (tryInstall("python3 -m pip install --user .")) {
+const result = run(
+  pythonCommand,
+  [...pythonPrefixArgs, "-m", "pip", "install", "--user", "."],
+  { stdio: "inherit" },
+);
+
+if (result.status === 0) {
   console.log("  \x1b[32m✓\x1b[0m kyp-mem installed successfully");
 } else {
-  console.log("  \x1b[33m!\x1b[0m Could not auto-install Python package.");
-  console.log("  \x1b[33m!\x1b[0m Run manually: pip install kyp-mem");
+  console.log("  \x1b[33m!\x1b[0m Could not auto-install the Python package.");
+  console.log(`  \x1b[33m!\x1b[0m Run manually from ${root}:`);
+  console.log("    python3 -m pip install --user .");
 }

package/kyp_mem/__init__.py

@@ -1,3 +1,3 @@
-"""KYP-MEM — Know Your Project Memory. Headless Obsidian for AI agents."""
+"""KYP-MEM — Know Your Project Memory. Headless knowledge base for AI agents."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

package/kyp_mem/cli.py

@@ -4,6 +4,7 @@ import os
 import json
 import shutil
 import argparse
+import subprocess
 from pathlib import Path
 
 C = "\033[36m"  # cyan
@@ -16,7 +17,7 @@ R = "\033[0m"   # reset
 def main():
     parser = argparse.ArgumentParser(
         prog="kyp-mem",
-        description="KYP-MEM — Know Your Project Memory. Headless Obsidian for AI agents.",
+        description="KYP-MEM — Know Your Project Memory. Headless knowledge base for AI agents.",
     )
     parser.add_argument("--vault", default=None, help="Override vault path")
 
@@ -74,7 +75,7 @@ def _run_init():
     print(f"{C}  ██║  ██╗   ██║   ██║           ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║{R}")
     print(f"{C}  ╚═╝  ╚═╝   ╚═╝   ╚═╝           ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝{R}")
     print()
-    print(f"  {D}Know Your Project — Headless Obsidian for AI agents{R}")
+    print(f"  {D}Know Your Project — Headless knowledge base for AI agents{R}")
     print()
     print(f"  {Y}>> First-time setup{R}")
     print()
@@ -107,20 +108,112 @@ def _run_setup_claude(global_config: bool = False):
     from .config import get_vault_path
 
     vault_path = get_vault_path()
+    mcp_command, mcp_args = _get_mcp_command()
+    claude_scope = "user" if global_config else "local"
+    scope_label = "global user" if global_config else "local project"
+
+    registered, detail = _register_with_claude_mcp(
+        claude_scope,
+        mcp_command,
+        mcp_args,
+        vault_path,
+    )
+
+    print()
+    print(f"  {C}KYP-MEM{R} — Claude Code Setup")
+    print()
+    if registered:
+        print(f"  {G}✓{R} MCP server registered with Claude Code ({scope_label})")
+    else:
+        settings_path = _write_legacy_claude_settings(global_config, mcp_command, mcp_args, vault_path)
+        print(f"  {Y}✗{R} Could not register with Claude Code's MCP manager")
+        print(f"  {D}  Reason:  {detail}{R}")
+        print(f"  {Y}!{R} Wrote legacy settings as a fallback")
+        print(f"  {D}  File:    {settings_path}{R}")
+    print(f"  {D}  Command: {mcp_command} {' '.join(mcp_args)}{R}")
+    print(f"  {D}  Vault:   {vault_path}{R}")
+    print()
+    print(f"  {C}Done!{R} Restart Claude Code and kyp-mem will run automatically.")
+    print(f"  Claude gets these tools: kyp_list, kyp_read, kyp_write, kyp_delete,")
+    print(f"  kyp_search, kyp_tags, kyp_related, kyp_recent, kyp_stats")
+    print()
+    print(f"  {D}To open the web UI anytime:{R} {Y}kyp-mem ui{R}")
+    print()
+
+
+def _get_mcp_command() -> tuple[str, list[str]]:
     kyp_mem_bin = shutil.which("kyp-mem")
+    npx_bin = shutil.which("npx")
+
+    if kyp_mem_bin and "_npx" not in Path(kyp_mem_bin).parts:
+        return kyp_mem_bin, ["serve"]
+    if npx_bin:
+        return npx_bin, ["-y", "kyp-mem", "serve"]
+
+    print(f"  {Y}Warning:{R} 'kyp-mem' not found in PATH.")
+    print(f"  {D}Make sure you installed with: npm install -g kyp-mem{R}")
+    print()
+    return "kyp-mem", ["serve"]
+
+
+def _register_with_claude_mcp(
+    scope: str,
+    mcp_command: str,
+    mcp_args: list[str],
+    vault_path: str,
+) -> tuple[bool, str]:
+    claude_bin = shutil.which("claude")
+    if not claude_bin:
+        return False, "'claude' CLI not found in PATH"
+
+    server_config = {
+        "type": "stdio",
+        "command": mcp_command,
+        "args": mcp_args,
+        "env": {
+            "KYP_VAULT": vault_path,
+        },
+    }
+
+    # Make setup idempotent when the user reruns it with a new vault or binary.
+    subprocess.run(
+        [claude_bin, "mcp", "remove", "-s", scope, "kyp-mem"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        text=True,
+    )
+
+    result = subprocess.run(
+        [
+            claude_bin,
+            "mcp",
+            "add-json",
+            "-s",
+            scope,
+            "kyp-mem",
+            json.dumps(server_config),
+        ],
+        capture_output=True,
+        text=True,
+    )
 
-    if not kyp_mem_bin:
-        print(f"  {Y}Warning:{R} 'kyp-mem' not found in PATH.")
-        print(f"  {D}Make sure you installed with: pip install kyp-mem{R}")
-        print()
-        kyp_mem_bin = "kyp-mem"
+    if result.returncode == 0:
+        return True, result.stdout.strip()
 
+    detail = (result.stderr or result.stdout or "unknown error").strip()
+    return False, detail
+
+
+def _write_legacy_claude_settings(
+    global_config: bool,
+    mcp_command: str,
+    mcp_args: list[str],
+    vault_path: str,
+) -> Path:
     if global_config:
         settings_path = Path.home() / ".claude" / "settings.json"
-        scope = "global"
     else:
         settings_path = Path.cwd() / ".claude" / "settings.json"
-        scope = "project"
 
     settings_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -132,31 +225,16 @@ def _run_setup_claude(global_config: bool = False):
             settings = {}
 
     mcp_servers = settings.setdefault("mcpServers", {})
-
     mcp_servers["kyp-mem"] = {
-        "command": kyp_mem_bin,
-        "args": ["serve"],
+        "command": mcp_command,
+        "args": mcp_args,
         "env": {
             "KYP_VAULT": vault_path,
         },
     }
 
     settings_path.write_text(json.dumps(settings, indent=2) + "\n")
-
-    print()
-    print(f"  {C}KYP-MEM{R} — Claude Code Setup")
-    print()
-    print(f"  {G}✓{R} MCP server added to {scope} settings")
-    print(f"  {D}  File:    {settings_path}{R}")
-    print(f"  {D}  Command: {kyp_mem_bin} serve{R}")
-    print(f"  {D}  Vault:   {vault_path}{R}")
-    print()
-    print(f"  {C}Done!{R} Restart Claude Code and kyp-mem will run automatically.")
-    print(f"  Claude gets these tools: kyp_list, kyp_read, kyp_write, kyp_delete,")
-    print(f"  kyp_search, kyp_tags, kyp_related, kyp_recent, kyp_stats")
-    print()
-    print(f"  {D}To open the web UI anytime:{R} {Y}kyp-mem ui{R}")
-    print()
+    return settings_path
 
 
 def _run_stats():
@@ -204,22 +282,37 @@ def _run_doctor():
     else:
         print(f"  {Y}✗{R} Vault not found: {vault_path}")
 
-    # Claude Code config
-    for label, path in [
+    # Claude Code MCP registration
+    claude_bin = shutil.which("claude")
+    if claude_bin:
+        result = subprocess.run(
+            [claude_bin, "mcp", "get", "kyp-mem"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0 and "Status: ✓ Connected" in result.stdout:
+            print(f"  {G}✓{R} Claude Code MCP: kyp-mem connected")
+        elif result.returncode == 0:
+            print(f"  {Y}✗{R} Claude Code MCP: kyp-mem registered but not connected")
+        else:
+            print(f"  {Y}✗{R} Claude Code MCP: kyp-mem not active")
+    else:
+        print(f"  {Y}✗{R} Claude Code CLI not found in PATH")
+
+    legacy_paths = [
         ("project", Path.cwd() / ".claude" / "settings.json"),
         ("global", Path.home() / ".claude" / "settings.json"),
-    ]:
-        if path.exists():
-            try:
-                s = json.loads(path.read_text())
-                if "kyp-mem" in s.get("mcpServers", {}):
-                    print(f"  {G}✓{R} Claude Code ({label}): kyp-mem configured")
-                else:
-                    print(f"  {D}·{R} Claude Code ({label}): exists but kyp-mem not configured")
-            except json.JSONDecodeError:
-                print(f"  {Y}✗{R} Claude Code ({label}): invalid JSON")
-        else:
-            print(f"  {D}·{R} Claude Code ({label}): no settings file")
+    ]
+    for label, path in legacy_paths:
+        if not path.exists():
+            continue
+        try:
+            s = json.loads(path.read_text())
+        except json.JSONDecodeError:
+            print(f"  {Y}✗{R} Legacy Claude settings ({label}): invalid JSON")
+            continue
+        if "kyp-mem" in s.get("mcpServers", {}):
+            print(f"  {D}·{R} Legacy Claude settings ({label}): kyp-mem entry present")
 
     # Binary
     kyp_bin = shutil.which("kyp-mem")
@@ -243,7 +336,7 @@ def _run_doctor():
 def _print_banner():
     print()
     print(f"{C}  KYP-MEM{R} — Know Your Project Memory")
-    print(f"  {D}Headless Obsidian for AI agents{R}")
+    print(f"  {D}Headless knowledge base for AI agents{R}")
     print()
 
 

package/kyp_mem/server.py

@@ -7,7 +7,7 @@ from .vault import Vault
 
 vault = Vault(get_vault_path())
 
-mcp = FastMCP("kyp-mem", description="Know Your Project — headless knowledge base like Obsidian")
+mcp = FastMCP("kyp-mem")
 
 
 @mcp.tool()

package/kyp_mem/ui.py

@@ -1,4 +1,4 @@
-"""KYP-MEM web UI — Obsidian-like interface for browsing the vault."""
+"""KYP-MEM web UI — interactive interface for browsing the vault."""
 
 import webbrowser
 from pathlib import Path

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "kyp-mem",
-  "version": "0.2.0",
-  "description": "Know Your Project — Headless Obsidian for AI agents. MCP-powered knowledge base with neon web UI.",
+  "version": "0.2.2",
+  "description": "Know Your Project — Headless knowledge base for AI agents. MCP-powered with wikilinks, backlinks, and neon web UI.",
   "bin": {
-    "kyp-mem": "./bin/cli.mjs"
+    "kyp-mem": "bin/cli.mjs"
   },
   "files": [
     "bin/",
-    "kyp_mem/",
+    "kyp_mem/*.py",
+    "kyp_mem/static/",
     "pyproject.toml",
     "README.md",
     "LICENSE"
@@ -17,7 +18,7 @@
   },
   "keywords": [
     "knowledge-base",
-    "obsidian",
+    "markdown",
     "ai",
     "mcp",
     "claude",
@@ -29,7 +30,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Adhithya-Karthikeyan/KYP-MEM.git"
+    "url": "git+https://github.com/Adhithya-Karthikeyan/KYP-MEM.git"
   },
   "homepage": "https://github.com/Adhithya-Karthikeyan/KYP-MEM"
 }

package/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kyp-mem"
-version = "0.2.0"
-description = "Know Your Project — Headless Obsidian for AI agents. MCP-powered knowledge base with neon web UI."
+version = "0.2.2"
+description = "Know Your Project — Headless knowledge base for AI agents. MCP-powered with wikilinks, backlinks, and neon web UI."
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.10"
 authors = [
-    {name = "KDB AI Agency", email = "dfreakhitman@gmail.com"}
+    {name = "KDB AI Agency", email = "skadhithya95@gmail.com"}
 ]
-keywords = ["knowledge-base", "obsidian", "ai", "mcp", "notes", "wiki", "second-brain"]
+keywords = ["knowledge-base", "markdown", "ai", "mcp", "notes", "wiki", "second-brain"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",