neo-cortex2-mcp 6.1.0__tar.gz

neo_cortex2_mcp-6.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+logs/
+neo-cortex.log
+cortex_db/
+neo-cortex.log.1
+*.log.1
+.lsai/
+
+# Postgres dev volume
+pgdata/
+.env
+
+# Throwaway forensic probes / experiments (never committed)
+tmp/

neo_cortex2_mcp-6.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: neo-cortex2-mcp
+Version: 6.1.0
+Summary: Neo Memory Cortex — Standalone Memory Server
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: fastmcp>=2.14.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: structlog>=24.0.0
+Requires-Dist: surrealdb>=2.0.0
+Requires-Dist: uvicorn>=0.34.0
+Requires-Dist: watchfiles>=1.0.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: claude
+Requires-Dist: claude-code-sdk>=0.0.1; extra == 'claude'
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'

neo_cortex2_mcp-6.1.0/mbel.md

@@ -0,0 +1,59 @@
+# MBEL v5 Grammar [IMMUTABLE]
+
+§MBEL:5.0
+@purpose::AIMemoryEncoding{compression%75,fidelity%100}
+
+## Operators [IMMUTABLE]
+
+### Core Set (27)
+```
+[Temporal:4]
+>   past/did/changed/was
+@   present/current/now/is
+?   future/todo/will/planned
+≈   around/circa/approximate/roughly
+
+[State:4]
+✓   complete/done/success/working
+✗   failed/broken/error/bug
+!   critical/important/priority/alert
+⚡  active/urgent/in-progress/hot
+
+[Relation:6]
+::  is/defines/equals/becomes
+→   leads_to/causes/then/produces
+←   comes_from/because/source/from
+↔   mutual/bidirectional/syncs/relates
++   and/with/combines/includes
+-   remove/delete/without/except
+
+[Structure:5]
+[]  section/category/namespace/group
+{}  metadata/attributes/properties/details
+()  note/comment/aside/remark
+|   or/alternative/choice/option
+<>  variant/template/placeholder/variable
+
+[Quantification:3]
+#   number/count/quantity/amount
+%   percentage/ratio/proportion/part
+~   approximately/range/between/around
+
+[Logic:3]
+&   AND/requires/must-have/with
+||  OR/either/can-be/allows
+¬   NOT/exclude/prevent/disable
+
+[Meta:2]
+©   source/origin/author/credit
+§   version/revision/protocol/schema
+```
+
+### Grammar Rules [IMMUTABLE]
+1. NoArticles(a/the/an)
+2. CamelCase→MultiWord
+3. ImplicitSubject{contextClear}
+4. OperatorsOnly¬Punctuation
+5. Newline::StatementSeparator
+6. LatestOverridesPrevious
+7. LeftToRight→Composition

neo_cortex2_mcp-6.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "neo-cortex2-mcp"
+version = "6.1.0"
+description = "Neo Memory Cortex — Standalone Memory Server"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn>=0.34.0",
+    "httpx>=0.28.0",
+    "pydantic>=2.10.0",
+    "fastmcp>=2.14.0",
+    "structlog>=24.0.0",
+    "pydantic-settings>=2.0.0",
+    "surrealdb>=2.0.0",
+    "watchfiles>=1.0.0",
+]
+
+[project.scripts]
+neo-cortex2-stop-hook = "neo_cortex.cli.stop_hook:cli"
+neo-cortex2-mcp = "neo_cortex.cli.mcp_server_v2:cli"
+neo-cortex2-dashboard = "neo_cortex.cli.dashboard_v2:cli"
+neo-cortex2-import = "neo_cortex.cli.import_logs:cli"
+neo-cortex2-rebuild = "neo_cortex.cli.rebuild_cli:cli"
+neo-cortex2-timeline = "neo_cortex.cli.timeline_v2:cli"
+
+[project.optional-dependencies]
+claude = ["claude-code-sdk>=0.0.1"]
+anthropic = ["anthropic>=0.40.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.25.0",
+    "pytest-httpx>=0.35.0",
+    "pyright>=1.1.0",
+    "pyyaml>=6.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/neo_cortex"]
+
+[tool.hatch.build.targets.wheel.shared-data]
+"src/neo_cortex/core/pipeline/prompts" = "neo_cortex/core/pipeline/prompts"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/neo_cortex/**", "mbel.md", "tests/**", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "unit: fast in-process unit test, no external dependencies",
+    "integration: requires external service (SurrealDB, etc.)",
+    "slow: long-running test, opt-in via -m slow",
+    "live_llm: hits a live LLM provider (OpenRouter); gated by RUN_LIVE_LLM_TESTS=1",
+    "e2e: end-to-end test with real SurrealDB, fake LLM/embedder",
+]
+filterwarnings = [
+    "error",
+    # CAUSA B — finalizzazione GC dell'async-generator `Connection.__aiter__` di websockets
+    # (v15.0.1, asyncio API), iterato in `_recv_task` del SDK surrealdb-py
+    # (`connections/async_ws.py:59` `async for data in self.socket`), finalizzato dal GC DOPO
+    # la chiusura del loop per-test di pytest-asyncio. NON è un leak nostro:
+    # misurato 1164 connessioni aperte = 1164 `close()` chiamate (0 non chiuse). Upstream, benigna.
+    # Pattern scoped al repr esatto dell'async-gen; il `.*` copre il prefisso "Exception ignored in:"
+    # (evita il `:` come separatore di campo). Verificato: matcha solo questo async-gen, non altri.
+    "ignore:.*async_generator object Connection\\.__aiter__:pytest.PytestUnraisableExceptionWarning",
+]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"

neo_cortex2_mcp-6.1.0/src/neo_cortex/assets/__init__.py

@@ -0,0 +1,10 @@
+"""Bundled assets for auto-setup (compose, model profiles, gitignore)."""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+
+def get_asset(name: str) -> Path:
+    """Return the filesystem path to a bundled asset file."""
+    return importlib.resources.files(__package__) / name

neo_cortex2_mcp-6.1.0/src/neo_cortex/assets/default-gitignore

@@ -0,0 +1,6 @@
+*.env
+.env
+cortex2.log
+cortex2_state/
+ingest-wake
+hooks-installed

neo_cortex2_mcp-6.1.0/src/neo_cortex/assets/default-models.json

@@ -0,0 +1,28 @@
+{
+    "active": "openrouter_default",
+    "profiles": {
+        "openrouter_default": {
+            "name": "DeepSeek v4 Flash via OpenRouter",
+            "description": "Default profile. Fast, cheap, high quality articulation.",
+            "provider": "openrouter",
+            "model": "deepseek/deepseek-v4-flash",
+            "reasoning_effort": "high",
+            "max_tokens": 300000
+        },
+        "gemini": {
+            "name": "Gemini 2.5 Flash",
+            "description": "Google Gemini via OpenRouter. Good quality, very cheap.",
+            "provider": "openrouter",
+            "model": "google/gemini-2.5-flash",
+            "reasoning_effort": "high",
+            "max_tokens": 65000
+        },
+        "groq": {
+            "name": "Llama 4 Scout via Groq",
+            "description": "Fastest inference. Groq direct API, no OpenRouter.",
+            "provider": "groq",
+            "model": "meta-llama/llama-4-scout-17b-16e-instruct",
+            "max_tokens": 8192
+        }
+    }
+}

neo_cortex2_mcp-6.1.0/src/neo_cortex/assets/docker-compose.yml

@@ -0,0 +1,37 @@
+name: cortex2
+
+services:
+  surrealdb:
+    image: surrealdb/surrealdb:v3.0.5
+    container_name: cortex-surrealdb
+    user: "0:0"
+    command: start --user ${SURREAL_USER:-root} --pass ${SURREAL_PASS:-root} rocksdb:/data/srdb
+    ports:
+      - "${SURREAL_PORT:-8000}:8000"
+    volumes:
+      - surreal-data:/data
+    healthcheck:
+      test: ["CMD", "/surreal", "is-ready"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    restart: unless-stopped
+
+  dashboard:
+    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+    container_name: cortex-dashboard
+    command: uvx --from neo-cortex-mcp neo-cortex2-dashboard
+    ports:
+      - "${DASHBOARD_PORT:-5075}:5075"
+    env_file: .env
+    environment:
+      UV_PRERELEASE: allow
+      CORTEX_STORAGE__SURREALDB_URL: http://surrealdb:8000
+      CORTEX2_DASHBOARD_HOST: "0.0.0.0"
+    depends_on:
+      surrealdb:
+        condition: service_healthy
+    restart: unless-stopped
+
+volumes:
+  surreal-data:

neo_cortex2_mcp-6.1.0/src/neo_cortex/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line entry points for cortex2."""

neo_cortex2_mcp-6.1.0/src/neo_cortex/cli/dashboard_v2.py

@@ -0,0 +1,78 @@
+"""cortex2 dashboard entrypoint — read-only FastAPI on port 5075.
+
+Boots `cortex2_web.dashboard.build_app(bundle)` against the same
+storage bundle the MCP server uses. NO worker tasks (the dashboard is
+read-only — it observes what the workers produce, never schedules work
+itself).
+
+Listens on port 5075 by default to coexist with the legacy dashboard on
+5074. Override via CORTEX2_DASHBOARD_PORT / CORTEX2_DASHBOARD_HOST.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+import structlog
+import uvicorn
+
+from neo_cortex.core.bundle import build_bundle, close_bundle
+from neo_cortex.core.config.schema import CortexConfig
+from neo_cortex.core.logging import configure_logging
+from neo_cortex.cortex2_web.dashboard import build_app
+
+log = structlog.get_logger(__name__)
+
+
+def _resolve_host() -> str:
+    return os.environ.get("CORTEX2_DASHBOARD_HOST", "127.0.0.1")
+
+
+def _resolve_port() -> int:
+    raw = os.environ.get("CORTEX2_DASHBOARD_PORT", "5075")
+    try:
+        return int(raw)
+    except ValueError:
+        return 5075
+
+
+async def _build_app_async() -> tuple:
+    config = CortexConfig.load()
+    configure_logging(config.logging)
+    bundle = await build_bundle(config)
+    app = build_app(bundle)
+    return app, bundle
+
+
+def cli(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="cortex2 dashboard — read-only FastAPI",
+    )
+    parser.add_argument("--host", default=None)
+    parser.add_argument("--port", type=int, default=None)
+    args = parser.parse_args(argv)
+
+    host = args.host or _resolve_host()
+    port = args.port or _resolve_port()
+
+    try:
+        app, bundle = asyncio.run(_build_app_async())
+    except Exception as e:  # noqa: BLE001
+        log.error("cortex2.dashboard.init_failed", error=str(e))
+        return 1
+
+    log.info("cortex2.dashboard.starting", host=host, port=port)
+    try:
+        uvicorn.run(app, host=host, port=port, log_level="info")
+    finally:
+        try:
+            asyncio.run(close_bundle(bundle))
+        except Exception:  # noqa: BLE001
+            pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli())

neo_cortex2_mcp-6.1.0/src/neo_cortex/cli/import_logs.py

@@ -0,0 +1,175 @@
+"""cortex2 importer — drain a legacy ConversationLog into bundle.turn_log.
+
+Source-agnostic: accepts any IConversationLogSource implementation.
+Today: `--source mongo --uri ... --db ... --ws ...` builds a
+MongoConversationLogSource. Tomorrow: `--source sqlite --path ...` will
+build the SQLite adapter (Plan 35) without changing this CLI.
+
+Idempotent: bundle.turn_log.append_if_new uses content_hash UNIQUE — a
+re-run on the same source skips already-imported turns. `--since-ts`
+acts as a coarse cursor for resume.
+
+Progress: structlog event every PROGRESS_EVERY rows.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from typing import Optional
+
+import structlog
+
+from neo_cortex.core.bundle import build_bundle, close_bundle
+from neo_cortex.core.config.schema import CortexConfig
+from neo_cortex.core.logging import configure_logging
+from neo_cortex.core.source import IConversationLogSource
+from neo_cortex.core.storage.entities import Turn
+from neo_cortex.core.storage.utils import compute_content_hash
+
+log = structlog.get_logger(__name__)
+
+PROGRESS_EVERY = 200
+
+
+async def _drain(
+    source: IConversationLogSource,
+    bundle,
+    *,
+    session_id_filter: Optional[str],
+    since_ts: Optional[float],
+    limit: Optional[int],
+) -> dict:
+    n_seen = 0
+    n_inserted = 0
+    n_skipped = 0
+    n_errors = 0
+    last_ts = since_ts or 0.0
+
+    async for turn in source.iter_entries(
+        session_id_filter=session_id_filter,
+        since_ts=since_ts,
+        limit=limit,
+    ):
+        n_seen += 1
+        # Compute content_hash here so re-runs are idempotent regardless
+        # of whether the source provides the column.
+        if turn.content_hash is None:
+            turn = Turn(
+                session_id=turn.session_id,
+                ts=turn.ts,
+                role=turn.role,
+                content=turn.content,
+                content_hash=compute_content_hash(turn),
+            )
+        try:
+            if hasattr(bundle.turn_log, "append_if_new"):
+                inserted = await bundle.turn_log.append_if_new(turn)
+                if inserted:
+                    n_inserted += 1
+                else:
+                    n_skipped += 1
+            else:
+                await bundle.turn_log.append(turn)
+                n_inserted += 1
+            last_ts = max(last_ts, turn.ts)
+        except Exception as e:  # noqa: BLE001 — keep draining on errors
+            n_errors += 1
+            log.warning(
+                "importer.row_failed",
+                ts=turn.ts, session=turn.session_id, error=str(e),
+            )
+
+        if n_seen % PROGRESS_EVERY == 0:
+            log.info(
+                "importer.progress",
+                seen=n_seen, inserted=n_inserted, skipped=n_skipped,
+                errors=n_errors, last_ts=last_ts,
+            )
+
+    return {
+        "seen": n_seen,
+        "inserted": n_inserted,
+        "skipped": n_skipped,
+        "errors": n_errors,
+        "last_ts": last_ts,
+    }
+
+
+def _build_source(args: argparse.Namespace) -> IConversationLogSource:
+    if args.source == "mongo":
+        if not args.mongo_uri or not args.mongo_db:
+            raise SystemExit(
+                "--source mongo requires --mongo-uri and --mongo-db"
+            )
+        from neo_cortex.core.source.mongo import (
+            MongoConversationLogSource,
+        )
+        return MongoConversationLogSource(
+            mongo_uri=args.mongo_uri,
+            db_name=args.mongo_db,
+            ws_name=args.ws,
+        )
+    raise SystemExit(f"unknown --source: {args.source}")
+
+
+async def _run(args: argparse.Namespace) -> int:
+    config = CortexConfig.load()
+    configure_logging(config.logging)
+    bundle = await build_bundle(config)
+    source = _build_source(args)
+    try:
+        stats = await _drain(
+            source, bundle,
+            session_id_filter=args.session_id,
+            since_ts=args.since_ts,
+            limit=args.limit,
+        )
+        log.info("importer.done", **stats)
+        print(
+            f"[importer] seen={stats['seen']} "
+            f"inserted={stats['inserted']} "
+            f"skipped(dup)={stats['skipped']} "
+            f"errors={stats['errors']} "
+            f"last_ts={stats['last_ts']}",
+        )
+        return 0 if stats["errors"] == 0 else 2
+    finally:
+        await source.close()
+        await close_bundle(bundle)
+
+
+def cli(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="cortex2 importer — drain legacy ConversationLog into "
+        "bundle.turn_log via storage Protocol",
+    )
+    parser.add_argument(
+        "--source", choices=["mongo"], required=True,
+        help="adapter selector (sqlite/jsonl coming in Plan 35)",
+    )
+    parser.add_argument("--ws", required=True, help="workspace name")
+    parser.add_argument("--mongo-uri", help="mongo connection URI")
+    parser.add_argument("--mongo-db", help="mongo database name")
+    parser.add_argument("--session-id", default=None, help="filter to one session")
+    parser.add_argument(
+        "--since-ts", type=float, default=None,
+        help="resume cursor — skip turns with ts <= value",
+    )
+    parser.add_argument(
+        "--limit", type=int, default=None,
+        help="cap on total imported turns (smoke runs)",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        return asyncio.run(_run(args))
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:  # noqa: BLE001
+        log.error("cortex2.import.fatal", error=str(e))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli())

neo_cortex2_mcp-6.1.0/src/neo_cortex/cli/init.py

@@ -0,0 +1,77 @@
+"""cortex init — atomic setup for a new ws + subscribed projects.
+
+Applies the LOGS_DDL to cortex_logs/<ws_name> and the PROJECTS_DDL to
+cortex_projects/<each subscribed project>. Idempotent — safe to run
+multiple times. Optionally writes a default `.cortex.env` if missing.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from neo_cortex.core.logging import get_logger
+from neo_cortex.core.storage.surrealdb.schema import apply_schema
+
+if TYPE_CHECKING:
+    from neo_cortex.core.storage.surrealdb.pool import SurrealPool
+
+log = get_logger(__name__)
+
+
+_DEFAULT_ENV = """\
+# cortex2 environment
+CORTEX_STORAGE__SURREALDB_URL=http://localhost:8000
+CORTEX_STORAGE__SURREALDB_USER=root
+CORTEX_STORAGE__SURREALDB_PASS=root
+CORTEX_LLM__PROVIDER=openrouter
+CORTEX_EMBEDDING__API_KEY=jina-key-here
+"""
+
+
+async def cortex_init(
+    ws_name: str,
+    projects: list[str],
+    pool: "SurrealPool",
+    env_path: Optional[Path] = None,
+    *,
+    logs_ns: str = "cortex_logs",
+    projects_ns: str = "cortex_projects",
+) -> int:
+    """Returns 0 on success, non-zero on failure."""
+    await apply_schema(pool, logs_ns, ws_name)
+    for p in projects:
+        await apply_schema(pool, projects_ns, p)
+
+    if env_path is not None and not env_path.exists():
+        env_path.write_text(_DEFAULT_ENV)
+        log.info("cortex_init.env_written", path=str(env_path))
+
+    log.info(
+        "cortex_init.done",
+        ws=ws_name, n_projects=len(projects),
+    )
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="cortex2 init")
+    parser.add_argument("--ws", required=True, help="workspace name")
+    parser.add_argument(
+        "--project", action="append", default=[],
+        help="subscribed project (repeatable)",
+    )
+    parser.add_argument(
+        "--env", help="path to write .cortex.env if missing",
+    )
+    args = parser.parse_args()
+    print(
+        f"cortex init --ws {args.ws} "
+        f"--projects {args.project} --env {args.env}"
+    )
+    print(
+        "Live wiring requires a SurrealPool — invoke cortex_init() "
+        "from the service container."
+    )
+    return 0