feat(memory): Serena-style markdown memory system + CLI (closes #60 phase-1)

README.md

@@ -2,12 +2,12 @@
 
 > **Before an AI writes a new class/id/function, CodeLens must be checked. This is not optional.**
 
-CodeLens is an AI-native code intelligence platform that gives AI agents **full visibility** into a codebase before they write any code. It prevents collision, overwrite of existing logic, security vulnerabilities, and dead code through 66 CLI commands, an MCP server with 64 tools (50 static + 14 dynamic), AST-based taint analysis, live CVE/OSV scanning, a plugin system with OWASP Top 10 + Compliance rule packs, a true graph data model (nodes + edges) for structural code queries, and token-efficient `--format compact` output for high-volume agent workflows (issue #17).
+CodeLens is an AI-native code intelligence platform that gives AI agents **full visibility** into a codebase before they write any code. It prevents collision, overwrite of existing logic, security vulnerabilities, and dead code through 67 CLI commands, an MCP server with 65 tools (50 static + 15 dynamic), AST-based taint analysis, live CVE/OSV scanning, a plugin system with OWASP Top 10 + Compliance rule packs, a true graph data model (nodes + edges) for structural code queries, and token-efficient `--format compact` output for high-volume agent workflows (issue #17).
 
 ## Features
 
-- **66 CLI Commands** — From basic scan/query to AST taint analysis, CVE scanning, plugin management, auto-fix, dashboards, CI/CD quality gates, and `graph-schema` for cheap graph-shape introspection
-- **MCP Server (64 Tools)** — Native AI agent integration via Model Context Protocol (JSON-RPC over stdio), 50 statically-defined tools + 14 dynamically discovered, every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`)
+- **67 CLI Commands** — From basic scan/query to AST taint analysis, CVE scanning, plugin management, auto-fix, dashboards, CI/CD quality gates, and `graph-schema` for cheap graph-shape introspection
+- **MCP Server (65 Tools)** — Native AI agent integration via Model Context Protocol (JSON-RPC over stdio), 50 statically-defined tools + 15 dynamically discovered, every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`)
 - **Token-Efficient Compact Output (v8.2, issue #17)** — `--format compact` produces single-char-key JSON with abbreviated types, omitted null fields, and relative paths — ~50% smaller than `json` on real trace output. Combined with `--limit`/`--offset` pagination, 5 structural queries now cost <5k tokens (down from 30-80k)
 - **AST Taint Engine** — Tree-sitter based taint analysis with return-value propagation, scope hierarchy, and branch condition refinement
 - **Live CVE/OSV Scanning** — Real-time vulnerability data from OSV.dev API with SQLite cache, 9 ecosystems (PyPI, npm, crates.io, Go, Maven, NuGet, RubyGems, Pub, Hex)
@@ -225,8 +225,8 @@ codelens/
 │   ├── changelog.md               # Older changelog (per-version highlights)
 │   └── agent-integration.md       # AI agent integration guide
 ├── scripts/
-│   ├── codelens.py                # CLI entry point (66 commands registered)
-│   ├── mcp_server.py              # MCP JSON-RPC server (64 tools)
+│   ├── codelens.py                # CLI entry point (67 commands registered)
+│   ├── mcp_server.py              # MCP JSON-RPC server (65 tools)
 │   ├── registry.py                # Registry read/write/build
 │   ├── persistent_registry.py     # SQLite persistent storage (WAL mode)
 │   ├── base_parser.py             # Base tree-sitter parser

SKILL-QUICK.md

@@ -114,7 +114,7 @@ $CLI list --limit 5 --offset 10 --format compact            # → paginated + co
 | "Cross-file taint" | `dataflow` | `taint` (taint is single-file, AST-deep) |
 | "Auto-fix issues" | `fix` | `check` (check just gates, doesn't fix) |
 
-## All 66 Commands
+## All 67 Commands
 
 ### Setup & Lifecycle (8+)
 `init` · `scan [--incremental] [--max-files N] [--full]` · `registry-validate` · `detect` · `watch [--debounce SECS] [--git-mode] [--interval SECS]` · `git-status` · `migrate` · `serve` · `lsp-status` (issue #33: `codelens --lsp-status` top-level flag is an alias of `codelens lsp-status` — both delegate to `hybrid_engine.get_lsp_status()` and return the identical payload)
@@ -146,19 +146,19 @@ $CLI list --limit 5 --offset 10 --format compact            # → paginated + co
 ### Tooling (1)
 `plugin <install|list|search|update|info|validate>`
 
-**Total: 66 commands** (auto-registered via `commands/__init__.py`; rerun `python3 scripts/sync_command_count.py --apply` after adding/removing a command)
+**Total: 67 commands** (auto-registered via `commands/__init__.py`; rerun `python3 scripts/sync_command_count.py --apply` after adding/removing a command)
 
-## MCP Server (64 Tools)
+## MCP Server (65 Tools)
 
 Start the MCP server for AI agent integration:
 
 ```bash
 python3 scripts/codelens.py serve
 ```
 
-Exposes 64 tools as `codelens_<command>` (e.g., `codelens_query`, `codelens_taint`, `codelens_graph_schema`, `codelens_architecture`, `codelens_resolve_types`, `codelens_git_status`):
+Exposes 65 tools as `codelens_<command>` (e.g., `codelens_query`, `codelens_taint`, `codelens_graph_schema`, `codelens_architecture`, `codelens_resolve_types`, `codelens_git_status`):
 - 50 statically-defined tools (full JSON schemas in `mcp_server.py`)
-- 14 dynamically-discovered tools (auto-discovered from `COMMAND_REGISTRY`; long-running `watch` and `serve` are excluded)
+- 15 dynamically-discovered tools (auto-discovered from `COMMAND_REGISTRY`; long-running `watch` and `serve` are excluded)
 - Every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`). Use `format: "compact"` for token-efficient responses (~50% smaller than `json`).
 - `watch` and `serve` itself are excluded (long-running)
 

SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: codelens
 description: >
-  CodeLens — AI-Native Code Intelligence. 66 commands for AI-powered code analysis,
+  CodeLens — AI-Native Code Intelligence. 67 commands for AI-powered code analysis,
   security auditing, quality scoring, AST-based taint analysis, live CVE scanning,
   and pre-write safety checks. Supports 28+ languages with tree-sitter + regex
-  fallback parsing. MCP server exposes 64 tools for AI agent integration.
+  fallback parsing. MCP server exposes 65 tools for AI agent integration.
   For quick command reference with validated output schemas, see SKILL-QUICK.md.
   For version history, see CHANGELOG.md.
 ---

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "codelens"
 version = "8.2.0"
-description = "Live Codebase Reference Intelligence — 66 commands for AI-powered code analysis, security auditing, and quality scoring"
+description = "Live Codebase Reference Intelligence — 67 commands for AI-powered code analysis, security auditing, and quality scoring"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.8"

scripts/commands/memory.py

@@ -0,0 +1,128 @@
+"""Memory command — Serena-style markdown memory system (issue #60).
+
+Provides cross-session memory for AI agents using CodeLens. Memory files are
+plain markdown stored under ``.codelens/memories/`` in the workspace (project
+scope) or ``~/.codelens/memories/global/`` (global scope, read-only via CLI).
+
+Usage::
+
+    codelens memory write <name> <content>   # create/update project memory
+    codelens memory read <name>              # read memory (project or global)
+    codelens memory list                     # list all memories
+    codelens memory delete <name>            # delete (project memory only)
+
+The storage layout, file header rules, and ``mem:NAME`` reference validation
+live in :mod:`memories.memory_manager` — this module is a thin CLI wrapper.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from commands import register_command
+
+
+def add_args(parser):
+    """Add memory subcommand arguments to the parser."""
+    sub = parser.add_subparsers(dest="memory_action", help="Memory action")
+
+    # memory write <name> <content>
+    write = sub.add_parser(
+        "write",
+        help="Create or update a project memory file",
+        description=(
+            "Create or update a project memory file at "
+            ".codelens/memories/<name>.md. The file is given a canonical "
+            "'# Memory: <name>' header. mem:NAME references in <content> are "
+            "validated and warnings are emitted for any references that do "
+            "not exist in project or global scope — the write itself always "
+            "succeeds (issue #60: warn, don't block)."
+        ),
+    )
+    write.add_argument("name", help="Memory topic name (e.g. 'auth-flow')")
+    write.add_argument(
+        "content",
+        help="Memory content (markdown). May include 'mem:NAME' references.",
+    )
+
+    # memory read <name>
+    read = sub.add_parser(
+        "read",
+        help="Read a memory file (project or global)",
+        description=(
+            "Read a memory file. Looks in the project scope first, then "
+            "falls back to the global scope. Returns 'not_found' if the "
+            "memory doesn't exist in either scope."
+        ),
+    )
+    read.add_argument("name", help="Memory topic name")
+
+    # memory list
+    sub.add_parser(
+        "list",
+        help="List all memory files (project + global)",
+        description=(
+            "List all memory files in project and global scope. Project "
+            "memories shadow global memories of the same name."
+        ),
+    )
+
+    # memory delete <name>
+    delete = sub.add_parser(
+        "delete",
+        help="Delete a project memory file",
+        description=(
+            "Delete a project memory file. Global memories are read-only "
+            "via CLI and cannot be deleted here — remove them manually from "
+            "~/.codelens/memories/global/ if needed."
+        ),
+    )
+    delete.add_argument("name", help="Memory topic name")
+
+
+def execute(args, workspace):
+    """Dispatch the memory subcommand."""
+    action = getattr(args, "memory_action", None)
+    if not action:
+        return {
+            "status": "error",
+            "error": "No memory action specified. Use: write, read, list, delete",
+            "usage": "codelens memory <write|read|list|delete> [args]",
+            "examples": [
+                "codelens memory write auth-flow 'Uses JWT, see mem:tokens'",
+                "codelens memory read auth-flow",
+                "codelens memory list",
+                "codelens memory delete auth-flow",
+            ],
+        }
+
+    # Lazy import so a broken memory_manager never breaks command discovery.
+    from memories.memory_manager import (
+        write_memory,
+        read_memory,
+        list_memories,
+        delete_memory,
+    )
+
+    if action == "write":
+        return write_memory(workspace, args.name, args.content)
+    if action == "read":
+        return read_memory(workspace, args.name)
+    if action == "list":
+        return list_memories(workspace)
+    if action == "delete":
+        return delete_memory(workspace, args.name)
+
+    return {
+        "status": "error",
+        "error": f"Unknown memory action: {action}",
+        "available_actions": ["write", "read", "list", "delete"],
+    }
+
+
+register_command(
+    "memory",
+    "Serena-style markdown memory system (write/read/list/delete)",
+    add_args,
+    execute,
+)

scripts/graph_model.py

@@ -13,7 +13,7 @@
 - New tables `graph_nodes` and `graph_edges` are additive (prefixed `graph_`
   to avoid colliding with any existing table name).
 - The flat registry tables and JSON files are untouched.
-- All 66 existing CLI commands continue to work unchanged.
+- All 67 existing CLI commands continue to work unchanged.
 
 Schema:
     graph_nodes(

scripts/memories/__init__.py

@@ -0,0 +1,13 @@
+"""CodeLens memory package — Serena-style markdown memory system (issue #60).
+
+Exposes the :mod:`memory_manager` module which implements CRUD for project
+and global memory files plus ``mem:NAME`` reference validation.
+
+Storage layout:
+- Project memory: ``<workspace>/.codelens/memories/<topic>.md``
+- Global memory:  ``~/.codelens/memories/global/<topic>.md`` (read-only via CLI)
+"""
+
+from . import memory_manager  # noqa: F401  (re-export for convenience)
+
+__all__ = ["memory_manager"]