stats

Instructions

Implementation Reference

• nexus_mcp.py:57-73 (handler)

  The calc_stats() function is the core handler for the 'stats' tool. It lists all memory files, groups them by tier, calculates counts, average strength, and active/decaying/archived breakdowns, returning a formatted string.

  def calc_stats():
      files = list_memory_files()
      total = len(files)
      by_tier = {}
      for f in files:
          by_tier.setdefault(f["tier"], []).append(f)
      lines = [f"Total: {total} memories"]
      for tier in TIERS:
          entries = by_tier.get(tier, [])
          if not entries:
              continue
          avg_s = sum(e["strength"] for e in entries) / len(entries)
          decaying = sum(1 for e in entries if 0.2 <= e["strength"] < 0.4)
          archived = sum(1 for e in entries if e["strength"] < 0.2)
          active = len(entries) - decaying - archived
          lines.append(f"  {tier}: {len(entries)} files | avg strength {avg_s:.2f} | {active} active, {decaying} decaying, {archived} archived")
      return "\n".join(lines)

• nexus_mcp.py:130-134 (schema)

  Tool definition/schema for 'stats' - declares the tool name, description, and an empty input schema (no parameters required).

  {
      "name": "stats",
      "description": "Show memory health statistics: file counts per tier, average strength, active/decaying/archived counts.",
      "inputSchema": {"type": "object", "properties": {}},
  },

• nexus_mcp.py:120-170 (registration)

  The TOOL_DEFS list registers all tools including 'stats' as part of the MCP server tool definitions. The handle_tools_list function returns these definitions.

  TOOL_DEFS = [
      {
          "name": "search",
          "description": "Search across all memory files by keyword. Returns matching file names, titles, strengths, and context snippets.",
          "inputSchema": {
              "type": "object",
              "properties": {"query": {"type": "string", "description": "Keyword or phrase to search for"}},
              "required": ["query"],
          },
      },
      {
          "name": "stats",
          "description": "Show memory health statistics: file counts per tier, average strength, active/decaying/archived counts.",
          "inputSchema": {"type": "object", "properties": {}},
      },
      {
          "name": "save",
          "description": "Save a new memory to a specified tier. Creates a markdown file with frontmatter. Use for recording new information, preferences, or experiences.",
          "inputSchema": {
              "type": "object",
              "properties": {
                  "tier": {
                      "type": "string",
                      "enum": ["episodic", "semantic", "procedural", "reflection", "working"],
                      "description": "Memory tier: episodic (experiences), semantic (facts/preferences), procedural (workflows), reflection (meta), working (in-session)",
                  },
                  "name": {"type": "string", "description": "Filename slug (no extension, use dashes: my-memory-name)"},
                  "content": {"type": "string", "description": "Full markdown content of the memory (including title heading)"},
                  "tags": {"type": "string", "description": "Comma-separated tags (optional)"},
              },
              "required": ["tier", "name", "content"],
          },
      },
      {
          "name": "touch",
          "description": "Boost a memory's strength (simulate access, counteracts Ebbinghaus decay). Use this when a memory is referenced or found relevant.",
          "inputSchema": {
              "type": "object",
              "properties": {
                  "name": {"type": "string", "description": "Memory filename (with or without .md extension)"},
                  "boost": {"type": "number", "description": "Strength boost amount (default 0.15, max 1.0)"},
              },
              "required": ["name"],
          },
      },
      {
          "name": "decay",
          "description": "Run a dry-run decay check. Calculates Ebbinghaus decay for all memories and reports which would be archived. Does NOT modify any files.",
          "inputSchema": {"type": "object", "properties": {}},
      },
  ]

• nexus_mcp.py:215-216 (registration)

  The handle_tools_call function dispatches to calc_stats() when the tool name is 'stats', returning the result as MCP text content.

  elif name == "stats":
      return {"content": [{"type": "text", "text": calc_stats()}]}, None

• nexus_mcp.py:28-55 (helper)

  The list_memory_files() helper function is called by calc_stats() to enumerate all memory files across tiers with their metadata (name, tier, strength, etc.).

  def list_memory_files():
      """Return list of {tier, name, path, title, strength, type} for all memories."""
      results = []
      for tier in TIERS:
          tier_dir = os.path.join(MEMORY_DIR, tier)
          if not os.path.isdir(tier_dir):
              continue
          for f in sorted(glob.glob(os.path.join(tier_dir, "*.md"))):
              name = os.path.splitext(os.path.basename(f))[0]
              with open(f, encoding="utf-8") as fh:
                  content = fh.read()
              title = ""
              for line in content.splitlines():
                  if line.startswith("# "):
                      title = line[2:]
                      break
              strength = parse_frontmatter(content, "strength") or "1.0"
              type_ = parse_frontmatter(content, "type") or tier
              results.append({
                  "uri": f"nexus://{tier}/{name}",
                  "name": name,
                  "title": title,
                  "tier": tier,
                  "strength": float(strength),
                  "type": type_,
                  "path": os.path.relpath(f, MEMORY_DIR),
              })
      return results